src/gromacs/utility/file.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::File.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_utility
  42  */
  43 #ifndef GMX_UTILITY_FILE_H
  44 #define GMX_UTILITY_FILE_H
  45
  46 #include <cstdio>
  47
  48 #include <string>
  49
  50 #include "gromacs/utility/common.h"
  51
  52 namespace gmx
  53 {
  54
  55 /*! \brief
  56  * Basic file object.
  57  *
  58  * This class provides basic file I/O functionality and uses exceptions
  59  * (FileIOError) for error reporting.
  60  *
  61  * \inpublicapi
  62  * \ingroup module_utility
  63  */
  64 class File
  65 {
  66     public:
  67         /*! \brief
  68          * Creates a file object and opens a file.
  69          *
  70          * \param[in] filename  Path of the file to open.
  71          * \param[in] mode      Mode to open the file in (for fopen()).
  72          * \throws    std::bad_alloc if out of memory.
  73          * \throws    FileIOError on any I/O error.
  74          *
  75          * \see open(const char *, const char *)
  76          */
  77         File(const char *filename, const char *mode);
  78         //! \copydoc File(const char *, const char *)
  79         File(const std::string &filename, const char *mode);
  80         /*! \brief
  81          * Destroys the file object.
  82          *
  83          * If the file is still open, it is closed.
  84          * Any error conditions will be ignored.
  85          */
  86         ~File();
  87
  88         /*! \brief
  89          * Opens a file.
  90          *
  91          * \param[in] filename  Path of the file to open.
  92          * \param[in] mode      Mode to open the file in (for fopen()).
  93          * \throws    FileIOError on any I/O error.
  94          *
  95          * The file object must not be open.
  96          */
  97         void open(const char *filename, const char *mode);
  98         //! \copydoc open(const char *, const char *)
  99         void open(const std::string &filename, const char *mode);
 100         /*! \brief
 101          * Closes the file object.
 102          *
 103          * \throws  FileIOError on any I/O error.
 104          *
 105          * The file must be open.
 106          */
 107         void close();
 108
 109         /*! \brief
 110          * Returns whether the file is an interactive terminal.
 111          *
 112          * Only works on Unix, otherwise always returns true.
 113          * It only makes sense to call this for File::standardInput() and
 114          * friends.
 115          *
 116          * Thie file must be open.
 117          * Does not throw.
 118          */
 119         bool isInteractive() const;
 120         /*! \brief
 121          * Returns a file handle for interfacing with C functions.
 122          *
 123          * The file must be open.
 124          * Does not throw.
 125          */
 126         FILE *handle();
 127
 128         /*! \brief
 129          * Reads given number of bytes from the file.
 130          *
 131          * \param[out] buffer  Pointer to buffer that receives the bytes.
 132          * \param[in]  bytes   Number of bytes to read.
 133          * \throws     FileIOError on any I/O error.
 134          *
 135          * The file must be open.
 136          */
 137         void readBytes(void *buffer, size_t bytes);
 138         /*! \brief
 139          * Reads a single line from the file.
 140          *
 141          * \param[out] line    String to receive the line.
 142          * \returns    false if nothing was read because the file ended.
 143          * \throws     std::bad_alloc if out of memory.
 144          * \throws     FileIOError on any I/O error.
 145          *
 146          * On error or when false is returned, \p line will be empty.
 147          * Trailing space will be removed from the line.
 148          * To loop over all lines in the file, use:
 149          * \code
 150            std::string line;
 151            while (file.readLine(&line))
 152            {
 153                // ...
 154            }
 155            \endcode
 156          */
 157         bool readLine(std::string *line);
 158         /*! \brief
 159          * Reads a single line from the file.
 160          *
 161          * \param[out] line    String to receive the line.
 162          * \returns    false if nothing was read because the file ended.
 163          * \throws     std::bad_alloc if out of memory.
 164          * \throws     FileIOError on any I/O error.
 165          *
 166          * On error or when false is returned, \p line will be empty.
 167          * Works as readLine(), except that terminating newline will be present
 168          * in \p line if it was present in the file.
 169          *
 170          * \see readLine()
 171          */
 172         bool readLineWithTrailingSpace(std::string *line);
 173
 174         /*! \brief
 175          * Writes a string to the file.
 176          *
 177          * \param[in]  str  String to write.
 178          * \throws     FileIOError on any I/O error.
 179          *
 180          * The file must be open.
 181          */
 182         void writeString(const char *str);
 183         //! \copydoc writeString(const char *)
 184         void writeString(const std::string &str) { writeString(str.c_str()); }
 185         /*! \brief
 186          * Writes a line to the file.
 187          *
 188          * \param[in]  line  Line to write.
 189          * \throws     FileIOError on any I/O error.
 190          *
 191          * If \p line does not end in a newline, one newline is appended.
 192          * Otherwise, works as writeString().
 193          *
 194          * The file must be open.
 195          */
 196         void writeLine(const char *line);
 197         //! \copydoc writeLine(const char *)
 198         void writeLine(const std::string &line) { writeLine(line.c_str()); }
 199         /*! \brief
 200          * Writes a newline to the file.
 201          *
 202          * \throws     FileIOError on any I/O error.
 203          */
 204         void writeLine();
 205
 206         /*! \brief
 207          * Checks whether a file exists and is a regular file.
 208          *
 209          * \param[in] filename  Path to the file to check.
 210          * \returns   true if \p filename exists and is accessible.
 211          *
 212          * Does not throw.
 213          */
 214         static bool exists(const char *filename);
 215         //! \copydoc exists(const char *)
 216         static bool exists(const std::string &filename);
 217
 218         /*! \brief
 219          * Returns a File object for accessing stdin.
 220          *
 221          * \throws    std::bad_alloc if out of memory (only on first call).
 222          */
 223         static File &standardInput();
 224         /*! \brief
 225          * Returns a File object for accessing stdout.
 226          *
 227          * \throws    std::bad_alloc if out of memory (only on first call).
 228          */
 229         static File &standardOutput();
 230         /*! \brief
 231          * Returns a File object for accessing stderr.
 232          *
 233          * \throws    std::bad_alloc if out of memory (only on first call).
 234          */
 235         static File &standardError();
 236
 237         /*! \brief
 238          * Reads contents of a file to a std::string.
 239          *
 240          * \param[in] filename  Name of the file to read.
 241          * \returns   The contents of \p filename.
 242          * \throws    std::bad_alloc if out of memory.
 243          * \throws    FileIOError on any I/O error.
 244          */
 245         static std::string readToString(const char *filename);
 246         //! \copydoc readToString(const char *)
 247         static std::string readToString(const std::string &filename);
 248         /*! \brief
 249          * Convenience method for writing a file from a string in a single call.
 250          *
 251          * \param[in] filename  Name of the file to read.
 252          * \param[in] text      String to write to \p filename.
 253          * \throws    FileIOError on any I/O error.
 254          *
 255          * If \p filename exists, it is overwritten.
 256          */
 257         static void writeFileFromString(const std::string &filename,
 258                                         const std::string &text);
 259
 260     private:
 261         /*! \brief
 262          * Initialize file object from an existing file handle.
 263          *
 264          * \param[in]  fp     %File handle to use (may be NULL).
 265          * \param[in]  bClose Whether this object should close its file handle.
 266          * \throws     std::bad_alloc if out of memory.
 267          *
 268          * Used internally to implement standardOutput() and standardError().
 269          */
 270         File(FILE *fp, bool bClose);
 271
 272         class Impl;
 273
 274         PrivateImplPointer<Impl> impl_;
 275 };
 276
 277 } // namespace gmx
 278
 279 #endif