src/support/docstream.h

   1 // -*- C++ -*-
   2 /**
   3  * \file docstream.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Georg Baum
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #ifndef LYX_DOCSTREAM_H
  13 #define LYX_DOCSTREAM_H
  14
  15 #include "support/docstring.h"
  16
  17 #include <fstream>
  18 #include <sstream>
  19
  20 namespace lyx {
  21
  22 class iconv_codecvt_facet_exception : public std::exception {
  23 public:
  24         virtual ~iconv_codecvt_facet_exception() throw() {}
  25         virtual const char * what() const throw();
  26 };
  27
  28 /// Base class for UCS4 input streams
  29 typedef std::basic_istream<char_type> idocstream;
  30
  31 /** Base class for UCS4 output streams.
  32     If you want to output a single UCS4 character, use \code
  33     os.put(c);
  34     \endcode, not \code
  35     os << c;
  36     \endcode . The latter will not output the character, but the code point
  37     as number if USE_WCHAR_T is not defined. This is because we can't overload
  38     operator<< (our character type is not always a real type but sometimes a
  39     typedef). Narrow characters of type char can be output as usual.
  40  */
  41 typedef std::basic_ostream<char_type> odocstream;
  42
  43 struct SetEnc;
  44
  45 /// File stream for reading UTF8-encoded files with automatic conversion to
  46 /// UCS4.
  47 /// Buffering must be switched off if the encoding is changed after
  48 /// construction by calling rdbuf()->pubsetbuf(0, 0).
  49 class ifdocstream : public std::basic_ifstream<char_type> {
  50         typedef std::basic_ifstream<char_type> base;
  51 public:
  52         ifdocstream();
  53         /// Create a stream with a specific encoding \p enc.
  54         /// We must not pass \p enc as string, to avoid confusing it with a file name.
  55         explicit ifdocstream(SetEnc const & enc);
  56         explicit ifdocstream(const char* s,
  57                 std::ios_base::openmode mode = std::ios_base::in,
  58                 std::string const & encoding = "UTF-8");
  59         ~ifdocstream() {}
  60 };
  61
  62 /// File stream for writing files in 8bit encoding \p encoding with automatic
  63 /// conversion from UCS4.
  64
  65 class ofdocstream : public std::basic_ofstream<char_type> {
  66         typedef std::basic_ofstream<char_type> base;
  67 public:
  68         ofdocstream();
  69         /// Create a stream with a specific encoding \p enc.
  70         /// We must not pass \p enc as string, to avoid confusing it with a file name.
  71         explicit ofdocstream(SetEnc const & enc);
  72         explicit ofdocstream(const char* s,
  73                 std::ios_base::openmode mode = std::ios_base::out|std::ios_base::trunc,
  74                 std::string const & encoding = "UTF-8");
  75         ~ofdocstream() {}
  76         ///
  77         void reset(std::string const & encoding);
  78 };
  79
  80
  81
  82 /// UCS4 input stringstream
  83 typedef std::basic_istringstream<char_type> idocstringstream;
  84
  85 /// UCS4 output manipulator
  86 typedef odocstream & (*odocstream_manip)(odocstream &);
  87
  88
  89 /// Helper struct for changing stream encoding
  90 struct SetEnc {
  91         /**
  92          * It is important that this constructor is explicit.
  93          * Otherwise the attempt to output a std::string to an odocstream
  94          * would compile, but cause a (probably failing) encoding change
  95          * instead of string output (we do not define
  96          * operator<<(odocstream &, std::string) since we want to avoid
  97          * outputting strings with unspecified encoding)
  98          */
  99         explicit SetEnc(std::string const & e) : encoding(e) {}
 100         std::string encoding;
 101 };
 102
 103 /// Helper function for changing stream encoding
 104 SetEnc setEncoding(std::string const & encoding);
 105
 106 /** Change the encoding of \p os to \p e.encoding.
 107     \p e.encoding must be a valid iconv name of an 8bit encoding.
 108     This does nothing if the stream is not a file stream, since only
 109     file streams do have an associated 8bit encoding.
 110     Usage: \code
 111     os << setEncoding("ISO-8859-1");
 112     \endcode
 113  */
 114 odocstream & operator<<(odocstream & os, SetEnc e);
 115 idocstream & operator<<(idocstream & os, SetEnc e);
 116
 117 }
 118
 119 #endif