anna
/
ocarina
1
0
Fork 0
Code Issues 7 Pull Requests Releases Wiki Activity

design: Update file design 

I'm starting to implement file access.  I've reread the design and
updated a few things to make it easier to test.

Signed-off-by: Bryan Schumaker <bjschuma@gmail.com>
This commit is contained in:
Bryan Schumaker 2013-07-27 11:39:05 -04:00 committed by Anna Schumaker
parent 72c7261ac8
commit 307bc88cb6
2 changed files with 130 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
design.txt
View File

@ -127,15 +127,19 @@ Audio: (lib/audio.cpp)
On-disk files: (lib/file.cpp)
I use the disk to store data between sessions, this could include
library state and user preferences. In theory, file formats do not
change often so updating between file formats should be possible.
Supporting all previous file formats can create a lot of clutter in
the code, so I will ONLY support updating from the previous file-format
version. Ocarina 5.x used two different numbers to represent the
current file format (library = 2 and playlist = 3). I want to unify
this into a single number shared across all files for simplicity, and
then create a class to read and write data on disk.
Data will be stored in the user's home directory according to the
XDG / freedesktop.org specification. This means storing data in
$XDG_DATA_HOME/ocarina{-debug|-test}/ and storing configuration in
$XDG_CONFIG_HOME/ocarina{-debug|-test}/. In addition, I will support
importing data from Ocarina 5.10 for conversion to the new format.
In theory my file format will not change often, so it should be
possible to use multiple Ocarina versions with the same data. However,
should the format need to change I will only support forward
compatibility. This means that downgrades will not be possible after
a file format change. To keep the code even cleaner, I will only
support updating from the previous file format version. This means
that legacy support will be removed after the first file format change.
Items should be written to a file with either a space or new line
separating multiple values.
@ -144,7 +148,14 @@ On-disk files: (lib/file.cpp)
File << aaaaa << bbbbb << endl is translated into "aaaaa bbbbb\n"
- File version:
#define FILE_VERSION 4
#define FILE_VERSION 0
- Hint where the file is located:
enum FileLocHint {
FILE_TYPE_CONFIG,
FILE_TYPE_DATA,
FILE_TYPE_LEGACY,
}
- Open mode:
enum OpenMode {
@ -161,31 +172,62 @@ On-disk files: (lib/file.cpp)
} f;
unsigned int version;
OpenMode mode;
FileLocHint hint;
string filepath;
public:
File(filepath);
open(OpenMode);
File(string, FileLocHint);
const char *get_filepath();
bool exists();
bool open(OpenMode);
const File &operator<<(File &);
const File &operator>>(File &);
getline(string &);
void getline(string &);
}
- File format:
File << FILE_VERSION << <OTHER_DATA>
File << FILE_VERSION << endl;
File << <OTHER_DATA> << endl;
- API:
File : File(filepath)
Resolve filepath to ~/.ocarina{-debug}/filepath
File : open(mode)
Open a file for either reading or writing.
If reading: Read in version from start of file
Else write version to file
File : File(string filepath, FileLocHint hint)
Resolve filepath to one of:
XDG_{CONFIG|DATA}_HOME/ocarina/filepath
XDG_{CONFIG|DATA}_HOME/ocarina-debug/filepath
XDG_{CONFIG|DATA}_HOME/ocarina-test/filepath
$HOME/.ocarina/
$HOME/.ocarina-debug/
const char *get_filepath()
Return the full filepath to the file.
bool File : exists()
Return true if the file exists in the filesystem.
Return false otherwise.
bool File : open(OpenMode mode)
When opening a file for reading (mode == OPEN_READ),
- Return false if the file does not exist
- Open the file
- Read in version from the start of the file
- Return true
When opening a file for writing (mode == OPEN_WRITE),
- Return false if the file has FILE_TYPE_LEGACY set
- Create missing directories as needed
- Write version information to the start of the file
- Return true
Return false if there are any errors opening the file.
File : operator<<()
Write data to out
Write data to the file.
File : operator>>()
Read data from in;
Read data from the file.
File : getline(string);
getline(f.in, string) to read an entire line
Read an entire line from the file, strip whitespace on either end

88
design/file.txt
View File

@ -8,15 +8,19 @@
version print
On-disk files: (lib/file.cpp)
I use the disk to store data between sessions, this could include
library state and user preferences. In theory, file formats do not
change often so updating between file formats should be possible.
Supporting all previous file formats can create a lot of clutter in
the code, so I will ONLY support updating from the previous file-format
version. Ocarina 5.x used two different numbers to represent the
current file format (library = 2 and playlist = 3). I want to unify
this into a single number shared across all files for simplicity, and
then create a class to read and write data on disk.
Data will be stored in the user's home directory according to the
XDG / freedesktop.org specification. This means storing data in
$XDG_DATA_HOME/ocarina{-debug|-test}/ and storing configuration in
$XDG_CONFIG_HOME/ocarina{-debug|-test}/. In addition, I will support
importing data from Ocarina 5.10 for conversion to the new format.
In theory my file format will not change often, so it should be
possible to use multiple Ocarina versions with the same data. However,
should the format need to change I will only support forward
compatibility. This means that downgrades will not be possible after
a file format change. To keep the code even cleaner, I will only
support updating from the previous file format version. This means
that legacy support will be removed after the first file format change.
Items should be written to a file with either a space or new line
separating multiple values.
@ -25,7 +29,14 @@ On-disk files: (lib/file.cpp)
File << aaaaa << bbbbb << endl is translated into "aaaaa bbbbb\n"
- File version:
#define FILE_VERSION 4
#define FILE_VERSION 0
- Hint where the file is located:
enum FileLocHint {
FILE_TYPE_CONFIG,
FILE_TYPE_DATA,
FILE_TYPE_LEGACY,
}
- Open mode:
enum OpenMode {
@ -42,28 +53,59 @@ On-disk files: (lib/file.cpp)
} f;
unsigned int version;
OpenMode mode;
FileLocHint hint;
string filepath;
public:
File(filepath);
open(OpenMode);
File(string, FileLocHint);
const char *get_filepath();
bool exists();
bool open(OpenMode);
const File &operator<<(File &);
const File &operator>>(File &);
getline(string &);
void getline(string &);
}
- File format:
File << FILE_VERSION << <OTHER_DATA>
File << FILE_VERSION << endl;
File << <OTHER_DATA> << endl;
- API:
File : File(filepath)
Resolve filepath to ~/.ocarina{-debug}/filepath
File : open(mode)
Open a file for either reading or writing.
If reading: Read in version from start of file
Else write version to file
File : File(string filepath, FileLocHint hint)
Resolve filepath to one of:
XDG_{CONFIG|DATA}_HOME/ocarina/filepath
XDG_{CONFIG|DATA}_HOME/ocarina-debug/filepath
XDG_{CONFIG|DATA}_HOME/ocarina-test/filepath
$HOME/.ocarina/
$HOME/.ocarina-debug/
const char *get_filepath()
Return the full filepath to the file.
bool File : exists()
Return true if the file exists in the filesystem.
Return false otherwise.
bool File : open(OpenMode mode)
When opening a file for reading (mode == OPEN_READ),
- Return false if the file does not exist
- Open the file
- Read in version from the start of the file
- Return true
When opening a file for writing (mode == OPEN_WRITE),
- Return false if the file has FILE_TYPE_LEGACY set
- Create missing directories as needed
- Write version information to the start of the file
- Return true
Return false if there are any errors opening the file.
File : operator<<()
Write data to out
Write data to the file.
File : operator>>()
Read data from in;
Read data from the file.
File : getline(string);
getline(f.in, string) to read an entire line
Read an entire line from the file, strip whitespace on either end