FileSystem.hpp
Go to the documentation of this file.
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 namespace file_system {
23 
24 /*!
25  * \ingroup FileSystemGroup
26  * \brief Wraps the dirname function to get the pathname of the parent directory
27  *
28  * See the opengroup documentation:
29  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html
30  *
31  * \example
32  * \snippet Test_FileSystem.cpp get_parent_path
33  *
34  * \requires `path` is a valid path on the filesystem
35  * \returns the path to the parent directory
36  */
38 
39 /*!
40  * \ingroup FileSystemGroup
41  * \brief Given a path to a file returns the file name
42  *
43  * \example
44  * \snippet Test_FileSystem.cpp get_file_name
45  *
46  * \requires `file_path` is a valid path on the filesystem
47  * \returns the file name
48  */
49 std::string get_file_name(const std::string& file_path);
50 
51 /*!
52  * \ingroup FileSystemGroup
53  * \brief Get the absolute path, resolving symlinks
54  *
55  * \requires `rel_path` is a valid path on the filesystem
56  * \returns the absolute path
57  */
59 
60 /*!
61  * \ingroup FileSystemGroup
62  * \brief Creates a directory, including any parents that don't exist. If the
63  * directory exists `create_directory` does nothing.
64  *
65  * \requires permissions to create `dir` on the filesystem
66  * \effects creates the directory `dir` on the filesystem
67  *
68  * \param dir the path where to create the directory
69  * \param wait_time time to wait in seconds between failures
70  * \param num_tries number of attempts to create directory (for slow
71  * filesystems)
72  */
73 void create_directory(const std::string& dir, double wait_time = 1,
74  size_t num_tries = 40);
75 
76 /*!
77  * \ingroup FileSystemGroup
78  * \brief Returns true if the directory exists
79  *
80  * \returns `true` if the directory exists
81  */
82 bool check_if_dir_exists(const std::string& dir);
83 
84 /*!
85  * \ingroup FileSystemGroup
86  * \brief Returns true if the regular file or link to the regular file exists.
87  *
88  * \note See the stat(2) documentation, e.g. at
89  * http://man7.org/linux/man-pages/man2/stat.2.html for details.
90  *
91  * \returns `true` if the file exists
92  */
93 bool check_if_file_exists(const std::string& file);
94 
95 /*!
96  * \ingroup FileSystemGroup
97  * \brief Returns true if the path points to a regular file or a link to a
98  * regular file.
99  *
100  * \note See the stat(2) documentation, e.g. at
101  * http://man7.org/linux/man-pages/man2/stat.2.html for details.
102  *
103  * \requires `path` is a valid path on the filesystem
104  * \returns `true` if `file` is a file, not a directory
105  */
106 bool is_file(const std::string& path);
107 
108 /*!
109  * \ingroup FileSystemGroup
110  * \brief Returns the file size in bytes
111  *
112  * \requires `file` is a valid file on the filesystem
113  * \returns size of `file` in bytes
114  */
115 size_t file_size(const std::string& file);
116 
117 /*!
118  * \ingroup FileSystemGroup
119  * \brief Returns the current working directory, resolving symlinks
120  */
121 std::string cwd();
122 
123 /*!
124  * \ingroup FileSystemGroup
125  * \brief Gets a list of files in a directory
126  *
127  * \returns vector of all files and directories inside `dir_name`
128  */
129 std::vector<std::string> ls(const std::string& dir_name = "./");
130 
131 /*!
132  * \ingroup FileSystemGroup
133  * \brief Deletes a file or directory.
134  *
135  * \requires `path` be a valid path on the filesystem
136  * \effects deletes `path` from the filesystem, if `recursive` is `true` then
137  * behaves like `rm -r`, otherwise like `rm` but will delete an empty directory
138  */
139 void rm(const std::string& path, bool recursive);
140 } // namespace file_system
void create_directory(const std::string &dir, const double wait_time, const size_t num_tries)
Creates a directory, including any parents that don&#39;t exist. If the directory exists create_directory...
Definition: FileSystem.cpp:96
bool check_if_file_exists(const std::string &file)
Returns true if the regular file or link to the regular file exists.
Definition: FileSystem.cpp:159
size_t file_size(const std::string &file)
Returns the file size in bytes.
Definition: FileSystem.cpp:177
std::string cwd()
Returns the current working directory, resolving symlinks.
Definition: FileSystem.cpp:188
std::string get_file_name(const std::string &file_path)
Given a path to a file returns the file name.
Definition: FileSystem.cpp:40
std::string get_parent_path(const std::string &path)
Wraps the dirname function to get the pathname of the parent directory.
Definition: FileSystem.cpp:31
A light-weight file system library based on POSIX.
Definition: FileSystem.cpp:29
bool is_file(const std::string &path)
Returns true if the path points to a regular file or a link to a regular file.
Definition: FileSystem.cpp:165
void rm(const std::string &path, bool recursive)
Deletes a file or directory.
Definition: FileSystem.cpp:234
std::vector< std::string > ls(const std::string &dir_name)
Gets a list of files in a directory.
Definition: FileSystem.cpp:211
std::string get_absolute_path(const std::string &rel_path)
Get the absolute path, resolving symlinks.
Definition: FileSystem.cpp:57
bool check_if_dir_exists(const std::string &dir)
Returns true if the directory exists.
Definition: FileSystem.cpp:153