src/gromacs/utility/file.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2012,2013,2014,2015, 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/classhelpers.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          * Opens a file and returns a `FILE` handle.
  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    FileIOError on any I/O error.
  73          *
  74          * Instead of returning `NULL` on errors, throws an exception with
  75          * additional details (including the file name and `errno`).
  76          */
  77         static FILE *openRawHandle(const char *filename, const char *mode);
  78         //! \copydoc openRawHandle(const char *, const char *)
  79         static FILE *openRawHandle(const std::string &filename, const char *mode);
  80         /*! \brief
  81          * Creates a file object and opens a file.
  82          *
  83          * \param[in] filename  Path of the file to open.
  84          * \param[in] mode      Mode to open the file in (for fopen()).
  85          * \throws    std::bad_alloc if out of memory.
  86          * \throws    FileIOError on any I/O error.
  87          *
  88          * \see open(const char *, const char *)
  89          */
  90         File(const char *filename, const char *mode);
  91         //! \copydoc File(const char *, const char *)
  92         File(const std::string &filename, const char *mode);
  93         /*! \brief
  94          * Destroys the file object.
  95          *
  96          * If the file is still open, it is closed.
  97          * Any error conditions will be ignored.
  98          */
  99         ~File();
 100
 101         /*! \brief
 102          * Opens a file.
 103          *
 104          * \param[in] filename  Path of the file to open.
 105          * \param[in] mode      Mode to open the file in (for fopen()).
 106          * \throws    FileIOError on any I/O error.
 107          *
 108          * The file object must not be open.
 109          */
 110         void open(const char *filename, const char *mode);
 111         //! \copydoc open(const char *, const char *)
 112         void open(const std::string &filename, const char *mode);
 113         /*! \brief
 114          * Closes the file object.
 115          *
 116          * \throws  FileIOError on any I/O error.
 117          *
 118          * The file must be open.
 119          */
 120         void close();
 121
 122         /*! \brief
 123          * Returns whether the file is an interactive terminal.
 124          *
 125          * Only works on Unix, otherwise always returns true.
 126          * It only makes sense to call this for File::standardInput() and
 127          * friends.
 128          *
 129          * Thie file must be open.
 130          * Does not throw.
 131          */
 132         bool isInteractive() const;
 133         /*! \brief
 134          * Returns a file handle for interfacing with C functions.
 135          *
 136          * The file must be open.
 137          * Does not throw.
 138          */
 139         FILE *handle();
 140
 141         /*! \brief
 142          * Reads given number of bytes from the file.
 143          *
 144          * \param[out] buffer  Pointer to buffer that receives the bytes.
 145          * \param[in]  bytes   Number of bytes to read.
 146          * \throws     FileIOError on any I/O error.
 147          *
 148          * The file must be open.
 149          */
 150         void readBytes(void *buffer, size_t bytes);
 151         /*! \brief
 152          * Reads a single line from the file.
 153          *
 154          * \param[out] line    String to receive the line.
 155          * \returns    false if nothing was read because the file ended.
 156          * \throws     std::bad_alloc if out of memory.
 157          * \throws     FileIOError on any I/O error.
 158          *
 159          * On error or when false is returned, \p line will be empty.
 160          * Trailing space will be removed from the line.
 161          * To loop over all lines in the file, use:
 162          * \code
 163            std::string line;
 164            while (file.readLine(&line))
 165            {
 166                // ...
 167            }
 168            \endcode
 169          */
 170         bool readLine(std::string *line);
 171         /*! \brief
 172          * Reads a single line from the file.
 173          *
 174          * \param[out] line    String to receive the line.
 175          * \returns    false if nothing was read because the file ended.
 176          * \throws     std::bad_alloc if out of memory.
 177          * \throws     FileIOError on any I/O error.
 178          *
 179          * On error or when false is returned, \p line will be empty.
 180          * Works as readLine(), except that terminating newline will be present
 181          * in \p line if it was present in the file.
 182          *
 183          * \see readLine()
 184          */
 185         bool readLineWithTrailingSpace(std::string *line);
 186
 187         /*! \brief
 188          * Writes a string to the file.
 189          *
 190          * \param[in]  str  String to write.
 191          * \throws     FileIOError on any I/O error.
 192          *
 193          * The file must be open.
 194          */
 195         void writeString(const char *str);
 196         //! \copydoc writeString(const char *)
 197         void writeString(const std::string &str) { writeString(str.c_str()); }
 198         /*! \brief
 199          * Writes a line to the file.
 200          *
 201          * \param[in]  line  Line to write.
 202          * \throws     FileIOError on any I/O error.
 203          *
 204          * If \p line does not end in a newline, one newline is appended.
 205          * Otherwise, works as writeString().
 206          *
 207          * The file must be open.
 208          */
 209         void writeLine(const char *line);
 210         //! \copydoc writeLine(const char *)
 211         void writeLine(const std::string &line) { writeLine(line.c_str()); }
 212         /*! \brief
 213          * Writes a newline to the file.
 214          *
 215          * \throws     FileIOError on any I/O error.
 216          */
 217         void writeLine();
 218
 219         /*! \brief
 220          * Checks whether a file exists and is a regular file.
 221          *
 222          * \param[in] filename  Path to the file to check.
 223          * \returns   true if \p filename exists and is accessible.
 224          *
 225          * Does not throw.
 226          */
 227         static bool exists(const char *filename);
 228         //! \copydoc exists(const char *)
 229         static bool exists(const std::string &filename);
 230
 231         /*! \brief
 232          * Returns a File object for accessing stdin.
 233          *
 234          * \throws    std::bad_alloc if out of memory (only on first call).
 235          */
 236         static File &standardInput();
 237
 238         /*! \brief
 239          * Reads contents of a file to a std::string.
 240          *
 241          * \param[in] filename  Name of the file to read.
 242          * \returns   The contents of \p filename.
 243          * \throws    std::bad_alloc if out of memory.
 244          * \throws    FileIOError on any I/O error.
 245          */
 246         static std::string readToString(const char *filename);
 247         //! \copydoc readToString(const char *)
 248         static std::string readToString(const std::string &filename);
 249         /*! \brief
 250          * Convenience method for writing a file from a string in a single call.
 251          *
 252          * \param[in] filename  Name of the file to read.
 253          * \param[in] text      String to write to \p filename.
 254          * \throws    FileIOError on any I/O error.
 255          *
 256          * If \p filename exists, it is overwritten.
 257          */
 258         static void writeFileFromString(const std::string &filename,
 259                                         const std::string &text);
 260
 261     private:
 262         /*! \brief
 263          * Initialize file object from an existing file handle.
 264          *
 265          * \param[in]  fp     %File handle to use (may be NULL).
 266          * \param[in]  bClose Whether this object should close its file handle.
 267          * \throws     std::bad_alloc if out of memory.
 268          *
 269          * Used internally to implement standardInput().
 270          */
 271         File(FILE *fp, bool bClose);
 272
 273         class Impl;
 274
 275         PrivateImplPointer<Impl> impl_;
 276 };
 277
 278 } // namespace gmx
 279
 280 #endif