path.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef COMMON_PATH_H
#define COMMON_PATH_H

#include "common/scummsys.h"
#include "common/str.h"
#include "common/str-array.h"

#ifdef CXXTEST_RUNNING
class PathTestSuite;
#endif

namespace Common {

class Path {
#ifdef CXXTEST_RUNNING
    friend class ::PathTestSuite;
#endif

private:
#ifndef RELEASE_BUILD
    static bool _shownSeparatorCollisionWarning;
#endif

    // The directory separator
    static const char SEPARATOR = '/';
    // The escape prefix character
    static const char ESCAPE = '|';
    // How the prefix character is escaped (doubling)
    static const char ESCAPED_ESCAPE = '|';
    // How the separator is escaped
    static const char ESCAPED_SEPARATOR  = '\\';

    String _str;

    static void escape(String &dst, char srcSeparator, const char *src, const char *end = nullptr);

    static String unescape(char dstSeparator, const char *src, const char *end = nullptr);

    static bool canUnescape(bool willBeAtBegin, bool wasAtBegin,
                            const char *begin, const char *end = nullptr);

    static inline bool needsEncoding(const char *str, char separator) {
        return *str && // String is not empty and
               (separator != SEPARATOR || // separator is not the one we use
                *str == ESCAPE); // or string begins with ESCAPE
    }

    static String encode(const char *str, char separator);

    Path extract(const char *begin, const char *end = nullptr) const;

    size_t findLastSeparator(size_t last = String::npos) const;

    template<typename T>
    T reduceComponents(T (*reducer)(T value, const String &element, bool last), T value) const;

    bool compareComponents(bool (*comparator)(const String &x, const String &y), const Path &other) const;

    static Path &punycode_decodefilename_helper(Path &path, const String &in, bool last);
    static Path &punycode_encodefilename_helper(Path &path, const String &in, bool last);

    inline bool isEscaped() const {
        // c_str() returns a null terminated string, if _str is empty we get \0
        return *_str.c_str() == ESCAPE;
    }

    const char *getSuffix(const Common::Path &other) const;

public:
    static const char kNoSeparator = '\x00';

#if defined(WIN32)
    static const char kNativeSeparator = '\\';
#else
    static const char kNativeSeparator = '/';
#endif

    struct IgnoreCaseAndMac_EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equalsIgnoreCaseAndMac(y); }
    };

    struct IgnoreCaseAndMac_Hash {
        uint operator()(const Path &x) const { return x.hashIgnoreCaseAndMac(); }
    };

    struct IgnoreCase_EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equalsIgnoreCase(y); }
    };

    struct IgnoreCase_Hash {
        uint operator()(const Path &x) const { return x.hashIgnoreCase(); }
    };

    struct EqualTo {
        bool operator()(const Path &x, const Path &y) const { return x.equals(y); }
    };

    struct Hash {
        uint operator()(const Path &x) const { return x.hash(); }
    };

    Path() {}

    Path(const Path &path) : _str(path._str) { }

    Path(const char *str, char separator = '/') :
        _str(needsEncoding(str, separator) ? encode(str, separator) : str) { }

    explicit Path(const String &str, char separator = '/') :
        _str(needsEncoding(str.c_str(), separator) ? encode(str.c_str(), separator) : str) { }

    String toString(char separator = '/') const;

    void clear() { _str.clear(); }

    Path getParent() const;

    Path getLastComponent() const;

    String baseName() const;

    bool operator==(const Path &x) const {
        return _str == x._str;
    }

    bool operator!=(const Path &x) const {
        return _str != x._str;
    }

    bool equals(const Path &x) const {
        return _str.equals(x._str);
    }
    bool equalsIgnoreCase(const Path &x) const;
    bool equalsIgnoreCaseAndMac(const Path &x) const;

    uint hash() const;
    uint hashIgnoreCase() const;
    uint hashIgnoreCaseAndMac() const;

    bool operator<(const Path &x) const;

    bool empty() const {
        return _str.empty();
    }

    Path &operator=(const Path &path) {
        _str = path._str;
        return *this;
    }

    Path &operator=(const char *str) {
        set(str);
        return *this;
    }

    Path &operator=(const String &str) {
        set(str.c_str());
        return *this;
    }

    void set(const char *str, char separator = '/') {
        if (needsEncoding(str, separator)) {
            _str = encode(str, separator);
        } else {
            _str = str;
        }
    }

    Path &appendInPlace(const Path &x);

    Path &appendInPlace(const String &str, char separator = '/') {
        appendInPlace(str.c_str(), separator);
        return *this;
    }

    Path &appendInPlace(const char *str, char separator = '/');

    WARN_UNUSED_RESULT Path append(const Path &x) const {
        Path temp(*this);
        temp.appendInPlace(x);
        return temp;
    }

    WARN_UNUSED_RESULT Path append(const String &str, char separator = '/') const {
        return append(str.c_str(), separator);
    }

    WARN_UNUSED_RESULT Path append(const char *str, char separator = '/') const {
        Path temp(*this);
        temp.appendInPlace(str, separator);
        return temp;
    }

    WARN_UNUSED_RESULT Path appendComponent(const char *str) const;

    WARN_UNUSED_RESULT Path appendComponent(const String &x) const {
        return appendComponent(x.c_str());
    }

    Path &joinInPlace(const Path &x);

    Path &joinInPlace(const String &str, char separator = '/') {
        return joinInPlace(str.c_str(), separator);
    }

    Path &joinInPlace(const char *str, char separator = '/');

    WARN_UNUSED_RESULT Path join(const Path &x) const {
        Path temp(*this);
        temp.joinInPlace(x);
        return temp;
    }

    WARN_UNUSED_RESULT Path join(const String &str, char separator = '/') const {
        return join(str.c_str(), separator);
    }

    WARN_UNUSED_RESULT Path join(const char *str, char separator = '/') const {
        Path temp(*this);
        temp.joinInPlace(str, separator);
        return temp;
    }

    Path &removeTrailingSeparators();

    bool isSeparatorTerminated() const { return _str.lastChar() == SEPARATOR; }

    bool isRelativeTo(const Common::Path &other) const { return getSuffix(other) != nullptr; }

    Path relativeTo(const Common::Path &other) const;

    Path punycodeDecode() const;

    Path punycodeEncode() const;

    void toLowercase() {
        // Escapism is not changed by changing case
        _str.toLowercase();
    }

    void toUppercase() {
        // Escapism is not changed by changing case
        _str.toUppercase();
    }

    bool matchPattern(const Path &pattern) const;

    Path normalize() const;

    StringArray splitComponents() const;

    static Path joinComponents(StringArray::const_iterator begin, StringArray::const_iterator end);
    static Path joinComponents(const StringArray &c) {
        return joinComponents(c.begin(), c.end());
    }

    String toConfig() const {
        return punycodeEncode().toString('/');
    }

    static Path fromConfig(const String &value);
};

} // End of namespace Common

#endif