1/**
2 * Copyright (c) 2006-2023 LOVE Development Team
3 *
4 * This software is provided 'as-is', without any express or implied
5 * warranty. In no event will the authors be held liable for any damages
6 * arising from the use of this software.
7 *
8 * Permission is granted to anyone to use this software for any purpose,
9 * including commercial applications, and to alter it and redistribute it
10 * freely, subject to the following restrictions:
11 *
12 * 1. The origin of this software must not be misrepresented; you must not
13 * claim that you wrote the original software. If you use this software
14 * in a product, an acknowledgment in the product documentation would be
15 * appreciated but is not required.
16 * 2. Altered source versions must be plainly marked as such, and must not be
17 * misrepresented as being the original software.
18 * 3. This notice may not be removed or altered from any source distribution.
19 **/
20
21#ifndef LOVE_FILESYSTEM_FILE_H
22#define LOVE_FILESYSTEM_FILE_H
23
24// STD
25#include <string>
26
27// LOVE
28#include "common/Data.h"
29#include "common/Object.h"
30#include "common/StringMap.h"
31#include "common/int.h"
32#include "FileData.h"
33
34namespace love
35{
36namespace filesystem
37{
38
39/**
40 * A File interface, providing generic means of reading from and
41 * writing to files.
42 **/
43class File : public Object
44{
45public:
46
47 static love::Type type;
48
49 /**
50 * File open mode.
51 **/
52 enum Mode
53 {
54 MODE_CLOSED,
55 MODE_READ,
56 MODE_WRITE,
57 MODE_APPEND,
58 MODE_MAX_ENUM
59 };
60
61 enum BufferMode
62 {
63 BUFFER_NONE,
64 BUFFER_LINE,
65 BUFFER_FULL,
66 BUFFER_MAX_ENUM
67 };
68
69 /**
70 * Used to indicate ALL data in a file.
71 **/
72 static const int64 ALL = -1;
73
74 /**
75 * Destructor.
76 **/
77 virtual ~File();
78
79 /**
80 * Opens the file in a certain mode.
81 *
82 * @param mode MODE_READ, MODE_WRITE, MODE_APPEND.
83 * @return True if successful, false otherwise.
84 **/
85 virtual bool open(Mode mode) = 0;
86
87 /**
88 * Closes the file.
89 *
90 * @return True if successful, false otherwise.
91 **/
92 virtual bool close() = 0;
93
94 /**
95 * Gets whether the file is open.
96 **/
97 virtual bool isOpen() const = 0;
98
99 /**
100 * Gets the size of the file.
101 *
102 * @return The size of the file.
103 **/
104 virtual int64 getSize() = 0;
105
106 /**
107 * Reads data from the file and allocates a Data object.
108 *
109 * @param size The number of bytes to attempt reading, or -1 for EOF.
110 * @return A newly allocated Data object.
111 **/
112 virtual FileData *read(int64 size = ALL);
113
114 /**
115 * Reads data into the destination buffer.
116 *
117 * @param dst The destination buffer.
118 * @param size The number of bytes to attempt reading.
119 * @return The number of bytes actually read.
120 **/
121 virtual int64 read(void *dst, int64 size) = 0;
122
123 /**
124 * Writes data into the File.
125 *
126 * @param data The source buffer.
127 * @param size The size of the buffer.
128 * @return True of success, false otherwise.
129 **/
130 virtual bool write(const void *data, int64 size) = 0;
131
132 /**
133 * Writes a Data object into the File.
134 *
135 * @param data The data object to write into the file.
136 * @param size The number of bytes to attempt writing, or -1 for everything.
137 * @return True of success, false otherwise.
138 **/
139 virtual bool write(const Data *data, int64 size = ALL);
140
141 /**
142 * Flushes the currently buffered file data to disk. Only applicable in
143 * write mode.
144 **/
145 virtual bool flush() = 0;
146
147 /**
148 * Checks whether we are currently at end-of-file.
149 *
150 * @return True if EOF, false otherwise.
151 **/
152 virtual bool isEOF() = 0;
153
154 /**
155 * Gets the current position in the File.
156 *
157 * @return The current byte position in the File.
158 **/
159 virtual int64 tell() = 0;
160
161 /**
162 * Seeks to a certain position in the File.
163 *
164 * @param pos The byte position in the file.
165 * @return True on success, false otherwise.
166 **/
167 virtual bool seek(uint64 pos) = 0;
168
169 /**
170 * Sets the buffering mode for the file. When buffering is enabled, the file
171 * will not write to disk (or will pre-load data if in read mode) until the
172 * buffer's capacity is reached.
173 * In the BUFFER_LINE mode, the file will also write to disk if a newline is
174 * written.
175 *
176 * @param bufmode The buffer mode.
177 * @param size The size in bytes of the buffer.
178 **/
179 virtual bool setBuffer(BufferMode bufmode, int64 size) = 0;
180
181 /**
182 * @param[out] size The size in bytes of the buffer.
183 * @return The current buffer mode.
184 **/
185 virtual BufferMode getBuffer(int64 &size) const = 0;
186
187 /**
188 * Gets the current mode of the File.
189 * @return The current mode of the File; CLOSED, READ, WRITE or APPEND.
190 **/
191 virtual Mode getMode() const = 0;
192
193 /**
194 * Gets the filename for this File, or empty string if none.
195 * @return The filename for this File.
196 **/
197 virtual const std::string &getFilename() const = 0;
198
199 /**
200 * Gets the file extension for this File, or empty string if none.
201 * @return The file extension for this File (without the dot).
202 **/
203 virtual std::string getExtension() const;
204
205 static bool getConstant(const char *in, Mode &out);
206 static bool getConstant(Mode in, const char *&out);
207 static std::vector<std::string> getConstants(Mode);
208
209 static bool getConstant(const char *in, BufferMode &out);
210 static bool getConstant(BufferMode in, const char *&out);
211 static std::vector<std::string> getConstants(BufferMode);
212
213private:
214
215 static StringMap<Mode, MODE_MAX_ENUM>::Entry modeEntries[];
216 static StringMap<Mode, MODE_MAX_ENUM> modes;
217
218 static StringMap<BufferMode, BUFFER_MAX_ENUM>::Entry bufferModeEntries[];
219 static StringMap<BufferMode, BUFFER_MAX_ENUM> bufferModes;
220
221}; // File
222
223} // filesystem
224} // love
225
226#endif // LOVE_FILESYSTEM_FILE_H
227