Line data    Source code

       1           1 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : /// \file
       5             : /// Declares functions to do file system manipulations
       6             : 
       7             : #pragma once
       8             : 
       9             : #include <cstddef>
      10             : #include <string>
      11             : #include <vector>
      12             : 
      13             : /*!
      14             :  * \ingroup FileSystemGroup
      15             :  * \brief A light-weight file system library based on POSIX.
      16             :  *
      17             :  * We use this library instead of a subprocess based library because OpenMPI
      18             :  * does not support forking of processes on all systems. Since the
      19             :  * parallelization library we use may be implemented on top of OpenMPI we
      20             :  * take the safe route and use POSIX.
      21             :  */
      22           1 : namespace file_system {
      23             : /*!
      24             :  * \ingroup FileSystemGroup
      25             :  * \brief Copies files or directories.
      26             :  *
      27             :  * Wrapper around `std::file_system::copy()`.
      28             :  */
      29           1 : void copy(const std::string& from, const std::string& to);
      30             : 
      31             : /*!
      32             :  * \ingroup FileSystemGroup
      33             :  * \brief Returns the current working directory, resolving symlinks
      34             :  */
      35           1 : std::string cwd();
      36             : 
      37             : /*!
      38             :  * \ingroup FileSystemGroup
      39             :  * \brief Creates a directory, including any parents that don't exist. If the
      40             :  * directory exists `create_directory` does nothing.
      41             :  *
      42             :  * \requires permissions to create `dir` on the filesystem
      43             :  * \effects creates the directory `dir` on the filesystem
      44             :  *
      45             :  * \param dir the path where to create the directory
      46             :  * \param wait_time time to wait in seconds between failures
      47             :  * \param num_tries number of attempts to create directory (for slow
      48             :  * filesystems)
      49             :  */
      50           1 : void create_directory(const std::string& dir, double wait_time = 1,
      51             :                       size_t num_tries = 40);
      52             : 
      53             : /*!
      54             :  * \ingroup FileSystemGroup
      55             :  * \brief Returns true if the directory exists
      56             :  *
      57             :  * \returns `true` if the directory exists
      58             :  */
      59           1 : bool check_if_dir_exists(const std::string& dir);
      60             : 
      61             : /*!
      62             :  * \ingroup FileSystemGroup
      63             :  * \brief Returns true if the regular file or link to the regular file exists.
      64             :  *
      65             :  * \note See the stat(2) documentation, e.g. at
      66             :  * http://man7.org/linux/man-pages/man2/stat.2.html for details.
      67             :  *
      68             :  * \returns `true` if the file exists
      69             :  */
      70           1 : bool check_if_file_exists(const std::string& file);
      71             : 
      72             : /*!
      73             :  * \ingroup FileSystemGroup
      74             :  * \brief Returns the file size in bytes
      75             :  *
      76             :  * \requires `file` is a valid file on the filesystem
      77             :  * \returns size of `file` in bytes
      78             :  */
      79           1 : size_t file_size(const std::string& file);
      80             : 
      81             : /*!
      82             :  * \ingroup FileSystemGroup
      83             :  * \brief Get the absolute path, resolving symlinks
      84             :  *
      85             :  * \requires `rel_path` is a valid path on the filesystem
      86             :  * \returns the absolute path
      87             :  */
      88           1 : std::string get_absolute_path(const std::string& rel_path);
      89             : 
      90             : /*!
      91             :  * \ingroup FileSystemGroup
      92             :  * \brief Given a path to a file returns the file name
      93             :  *
      94             :  * \example
      95             :  * \snippet Test_FileSystem.cpp get_file_name
      96             :  *
      97             :  * \requires `file_path` is a valid path on the filesystem
      98             :  * \returns the file name
      99             :  */
     100           1 : std::string get_file_name(const std::string& file_path);
     101             : 
     102             : /*!
     103             :  * \ingroup FileSystemGroup
     104             :  * \brief Wraps the dirname function to get the pathname of the parent directory
     105             :  *
     106             :  * See the opengroup documentation:
     107             :  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html
     108             :  *
     109             :  * \example
     110             :  * \snippet Test_FileSystem.cpp get_parent_path
     111             :  *
     112             :  * \requires `path` is a valid path on the filesystem
     113             :  * \returns the path to the parent directory
     114             :  */
     115           1 : std::string get_parent_path(const std::string& path);
     116             : 
     117             : /*!
     118             :  * \ingroup FileSystemGroup
     119             :  * \brief Get a list of files matching the given glob pattern
     120             :  */
     121           1 : std::vector<std::string> glob(const std::string& pattern);
     122             : 
     123             : /*!
     124             :  * \ingroup FileSystemGroup
     125             :  * \brief Returns true if the path points to a regular file or a link to a
     126             :  * regular file.
     127             :  *
     128             :  * \note See the stat(2) documentation, e.g. at
     129             :  * http://man7.org/linux/man-pages/man2/stat.2.html for details.
     130             :  *
     131             :  * \requires `path` is a valid path on the filesystem
     132             :  * \returns `true` if `file` is a file, not a directory
     133             :  */
     134           1 : bool is_file(const std::string& path);
     135             : 
     136             : /*!
     137             :  * \ingroup FileSystemGroup
     138             :  * \brief Gets a list of files in a directory
     139             :  *
     140             :  * \returns vector of all files and directories inside `dir_name`
     141             :  */
     142           1 : std::vector<std::string> ls(const std::string& dir_name = "./");
     143             : 
     144             : /*!
     145             :  * \ingroup FileSystemGroup
     146             :  * \brief Deletes a file or directory.
     147             :  *
     148             :  * \requires `path` be a valid path on the filesystem
     149             :  * \effects deletes `path` from the filesystem, if `recursive` is `true` then
     150             :  * behaves like `rm -r`, otherwise like `rm` but will delete an empty directory
     151             :  */
     152           1 : void rm(const std::string& path, bool recursive);
     153             : }  // namespace file_system