1/* $Id: CoinFileIO.hpp 1448 2011-06-19 15:34:41Z stefan $ */
2// Copyright (C) 2005, COIN-OR. All Rights Reserved.
3// This code is licensed under the terms of the Eclipse Public License (EPL).
4
5#ifndef CoinFileIO_H
6#define CoinFileIO_H
7
8#include <string>
9
10/// Base class for FileIO classes.
11class CoinFileIOBase
12{
13public:
14 /// Constructor.
15 /// @param fileName The name of the file used by this object.
16 CoinFileIOBase (const std::string &fileName);
17
18 /// Destructor.
19 ~CoinFileIOBase ();
20
21 /// Return the name of the file used by this object.
22 const char *getFileName () const;
23
24 /// Return the method of reading being used
25 inline std::string getReadType () const
26 { return readType_.c_str();}
27protected:
28 std::string readType_;
29private:
30 CoinFileIOBase ();
31 CoinFileIOBase (const CoinFileIOBase &);
32
33 std::string fileName_;
34};
35
36/// Abstract base class for file input classes.
37class CoinFileInput: public CoinFileIOBase
38{
39public:
40 /// indicates whether CoinFileInput supports gzip'ed files
41 static bool haveGzipSupport();
42 /// indicates whether CoinFileInput supports bzip2'ed files
43 static bool haveBzip2Support();
44
45 /// Factory method, that creates a CoinFileInput (more precisely
46 /// a subclass of it) for the file specified. This method reads the
47 /// first few bytes of the file and determines if this is a compressed
48 /// or a plain file and returns the correct subclass to handle it.
49 /// If the file does not exist or uses a compression not compiled in
50 /// an exception is thrown.
51 /// @param fileName The file that should be read.
52 static CoinFileInput *create (const std::string &fileName);
53
54 /// Constructor (don't use this, use the create method instead).
55 /// @param fileName The name of the file used by this object.
56 CoinFileInput (const std::string &fileName);
57
58 /// Destructor.
59 virtual ~CoinFileInput ();
60
61 /// Read a block of data from the file, similar to fread.
62 /// @param buffer Address of a buffer to store the data into.
63 /// @param size Number of bytes to read (buffer should be large enough).
64 /// @return Number of bytes read.
65 virtual int read (void *buffer, int size) = 0;
66
67 /// Reads up to (size-1) characters an stores them into the buffer,
68 /// similar to fgets.
69 /// Reading ends, when EOF or a newline occurs or (size-1) characters have
70 /// been read. The resulting string is terminated with '\0'. If reading
71 /// ends due to an encoutered newline, the '\n' is put into the buffer,
72 /// before the '\0' is appended.
73 /// @param buffer The buffer to put the string into.
74 /// @param size The size of the buffer in characters.
75 /// @return buffer on success, or 0 if no characters have been read.
76 virtual char *gets (char *buffer, int size) = 0;
77};
78
79/// Abstract base class for file output classes.
80class CoinFileOutput: public CoinFileIOBase
81{
82public:
83
84 /// The compression method.
85 enum Compression {
86 COMPRESS_NONE = 0, ///< No compression.
87 COMPRESS_GZIP = 1, ///< gzip compression.
88 COMPRESS_BZIP2 = 2 ///< bzip2 compression.
89 };
90
91 /// Returns whether the specified compression method is supported
92 /// (i.e. was compiled into COIN).
93 static bool compressionSupported (Compression compression);
94
95 /// Factory method, that creates a CoinFileOutput (more precisely
96 /// a subclass of it) for the file specified. If the compression method
97 /// is not supported an exception is thrown (so use compressionSupported
98 /// first, if this is a problem). The reason for not providing direct
99 /// access to the subclasses (and using such a method instead) is that
100 /// depending on the build configuration some of the classes are not
101 /// available (or functional). This way we can handle all required ifdefs
102 /// here instead of polluting other files.
103 /// @param fileName The file that should be read.
104 /// @param compression Compression method used.
105 static CoinFileOutput *create (const std::string &fileName,
106 Compression compression);
107
108 /// Constructor (don't use this, use the create method instead).
109 /// @param fileName The name of the file used by this object.
110 CoinFileOutput (const std::string &fileName);
111
112 /// Destructor.
113 virtual ~CoinFileOutput ();
114
115 /// Write a block of data to the file, similar to fwrite.
116 /// @param buffer Address of a buffer containing the data to be written.
117 /// @param size Number of bytes to write.
118 /// @return Number of bytes written.
119 virtual int write (const void * buffer, int size) = 0;
120
121 /// Write a string to the file (like fputs).
122 /// Just as with fputs no trailing newline is inserted!
123 /// The terminating '\0' is not written to the file.
124 /// The default implementation determines the length of the string
125 /// and calls write on it.
126 /// @param s The zero terminated string to be written.
127 /// @return true on success, false on error.
128 virtual bool puts (const char *s);
129
130 /// Convenience method: just a 'puts(s.c_str())'.
131 inline bool puts (const std::string &s)
132 {
133 return puts (s.c_str ());
134 }
135};
136
137/*! \relates CoinFileInput
138 \brief Test if the given string looks like an absolute file path
139
140 The criteria are:
141 - unix: string begins with `/'
142 - windows: string begins with `\' or with `drv:' (drive specifier)
143*/
144bool fileAbsPath (const std::string &path) ;
145
146/*! \relates CoinFileInput
147 \brief Test if the file is readable, using likely versions of the file
148 name, and return the name that worked.
149
150 The file name is constructed from \p name using the following rules:
151 <ul>
152 <li> An absolute path is not modified.
153 <li> If the name begins with `~', an attempt is made to replace `~'
154 with the value of the environment variable HOME.
155 <li> If a default prefix (\p dfltPrefix) is provided, it is
156 prepended to the name.
157 </ul>
158 If the constructed file name cannot be opened, and CoinUtils was built
159 with support for compressed files, fileCoinReadable will try any
160 standard extensions for supported compressed files.
161
162 The value returned in \p name is the file name that actually worked.
163*/
164bool fileCoinReadable(std::string &name,
165 const std::string &dfltPrefix = std::string(""));
166#endif
167