Exheredludis/paludis/util/fs_path.hh

/* vim: set sw=4 sts=4 et foldmethod=syntax : */

/*
 * Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011 Ciaran McCreesh
 * Copyright (c) 2006 Mark Loeser
 * Copyright (c) 2008 Fernando J. Pereda
 *
 * This file is part of the Paludis package manager. Paludis is free software;
 * you can redistribute it and/or modify it under the terms of the GNU General
 * Public License version 2, as published by the Free Software Foundation.
 *
 * Paludis 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, write to the Free Software Foundation, Inc., 59 Temple
 * Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef PALUDIS_GUARD_PALUDIS_UTIL_FS_PATH_HH
#define PALUDIS_GUARD_PALUDIS_UTIL_FS_PATH_HH 1

#include <paludis/util/fs_path-fwd.hh>
#include <paludis/util/fs_stat-fwd.hh>
#include <paludis/util/timestamp-fwd.hh>
#include <paludis/util/pimp.hh>
#include <sys/stat.h>

namespace paludis
{
    class PALUDIS_VISIBLE FSPath
    {
        friend std::ostream & paludis::operator<< (std::ostream & s, const FSPath & f);
        friend bool operator== (const FSPath &, const FSPath &);

        private:
            Pimp<FSPath> _imp;

            void _normalise();

        public:
            explicit FSPath(const std::string &);

            FSPath(const FSPath &);

            FSPath & operator= (const FSPath &);

            ~FSPath();

            FSStat stat() const PALUDIS_ATTRIBUTE((warn_unused_result));

            FSPath operator/ (const std::string &) const PALUDIS_ATTRIBUTE((warn_unused_result));
            FSPath operator/ (const FSPath &) const PALUDIS_ATTRIBUTE((warn_unused_result));

            FSPath & operator/= (const std::string &);
            FSPath & operator/= (const FSPath &);

            /**
             * Return the last part of our path (eg '/foo/bar' => 'bar').
             */
            const std::string basename() const PALUDIS_ATTRIBUTE((warn_unused_result));

            /**
             * Return the first part of our path (eg '/foo/bar' => '/foo').
             */
            FSPath dirname() const
                PALUDIS_ATTRIBUTE((warn_unused_result));

            /**
             * Return the canonicalised version of our path.
             */
            FSPath realpath() const PALUDIS_ATTRIBUTE((warn_unused_result));

            /**
             * Return the canonicalised version of our path, if it exists, or
             * ourself if it doesn't.
             */
            FSPath realpath_if_exists() const PALUDIS_ATTRIBUTE((warn_unused_result));

            /**
             * Return the path without a given prefix (eg '/foo/bar/baz'->strip_leading('/foo') => '/bar/baz').
             */
            FSPath strip_leading(const FSPath & prefix) const;

            /**
             * Do we start with a given path (eg '/foo/bar' starts with '/foo'
             * but not '/fo')?
             */
            bool starts_with(const FSPath &) const;

            /**
             * Try to make a directory.
             *
             * \return True, if we succeeded, and false if the directory
             *     already exists and is a directory and options includes
             *     fspmkdo_ok_if_exists.
             *
             * \exception FSError If an error other than the directory already
             *   existing occurs, or if the directory already exists and
             *   options does not include fspmkdo_ok_if_exists.
             */
            bool mkdir(const mode_t mode, const FSPathMkdirOptions &) const;

            /**
             * Try to make a symlink.
             *
             * \return True, if we succeeded, and false if the target already
             *   exists and is a symlink to the same target.
             *
             * \exception FSError If an error other than the symlink already
             *   existing occurs, or if the symlink exists and points elsewhere.
             */
            bool symlink(const std::string & target) const;

            /**
             * Try to unlink.
             *
             * \return True, if we succeeded, and false if we don't exist
             *   already.
             *
             * \exception FSError If an error other than us already not
             *   existing occurs.
             */
            bool unlink() const;

            /**
             * Try to rmdir.
             *
             * \return True, if we succeeded, and false if we don't exist
             *   already.
             *
             * \exception FSError If an error other than us already not
             *   existing occurs.
             */
            bool rmdir() const;

            /**
             * Change our ownership, following symlinks.
             *
             * \exception FSError If the chown failed.
             */
            void chown(const uid_t owner, const gid_t group) const;

            /**
             * Change our ownership, not following symlinks.
             *
             * \exception FSError If the lchown failed.
             */
            void lchown(const uid_t owner, const gid_t group) const;

            /**
             * Change our permissions.
             *
             * \exception FSError If the chmod failed.
             */
            void chmod(const mode_t mode) const;

            /**
             * Try to set atime and mtime
             *
             * \return True, if we succeeded, and false if we don't exist
             *   already.
             *
             * \exception FSError If an error other than us already not
             *   existing ocurrs.
             */
            bool utime(const Timestamp &) const;

            /**
             * Return our destination, if we are a symlink.
             *
             * \exception FSError if we are not a symlink, or if the system call
             * fails.
             */
            std::string readlink() const PALUDIS_ATTRIBUTE((warn_unused_result));

            /**
             * Rename ourself (will not work across mount points).
             *
             * \exception FSError If the rename failed.
             */
            void rename(const FSPath & new_name) const;

            /**
             * Return the current working directory
             */
            static FSPath cwd() PALUDIS_ATTRIBUTE((warn_unused_result));
    };

    class PALUDIS_VISIBLE FSPathComparator
    {
        public:
            bool operator() (const FSPath &, const FSPath &) const;
    };

    extern template class Pimp<FSPath>;
}

#endif