PropWare  3.0.0.229
C++ objects and CMake build system for Parallax Propeller
Public Types | Public Member Functions | Static Public Attributes | List of all members
PropWare::FatFileReader Class Referenceabstract

Read a file on a FAT 16 or FAT 32 storage device. More...

#include <PropWare/filesystem/fat/fatfilereader.h>

+ Inheritance diagram for PropWare::FatFileReader:
+ Collaboration diagram for PropWare::FatFileReader:

Public Types

enum  ErrorCode {
  NO_ERROR = 0,
  BEG_ERROR = Filesystem::END_ERROR + 1,
  ENTRY_NOT_FILE = BEG_ERROR,
  FILENAME_NOT_FOUND,
  END_ERROR = FILENAME_NOT_FOUND
}
 
enum  SeekDir {
  SeekDir::BEG,
  SeekDir::CUR,
  SeekDir::END
}
 

Public Member Functions

 FatFileReader (FatFS &fs, const char name[], BlockStorage::Buffer &buffer=SHARED_BUFFER, const Printer &logger=pwOut)
 Construct a new file instance. More...
 
PropWare::ErrorCode open ()
 Open the file. More...
 
PropWare::ErrorCode safe_get_char (char &c)
 Read a character from the file. More...
 
const charget_name () const
 Determine the name of a file. More...
 
bool exists () const
 Determine if a file exists (file does not have to be open) More...
 
bool exists (PropWare::ErrorCode &err) const
 
virtual PropWare::ErrorCode close ()
 Close a file - a required step in any workflow that includes opening a file. More...
 
virtual PropWare::ErrorCode flush ()=0
 Flush any modified data back to the SD card. More...
 
int32_t get_length () const
 Return the number of bytes (characters) in the file.
 
int32_t tell () const
 Obtain the value of the file position indicator. More...
 
PropWare::ErrorCode seek (const int32_t offset, const SeekDir way)
 Sets the position of the next character to be read or written. More...
 
PropWare::ErrorCode seek (const int32_t position)
 
PropWare::ErrorCode flush ()
 Flush any modified data back to the SD card. More...
 
char get_char ()
 Read a character from the file. More...
 
bool eof () const
 Determine whether the read pointer has reached the end of the file. More...
 
PropWare::ErrorCode safe_peek (char &c)
 Read a character from the file without incrementing the pointer. More...
 
char peek ()
 Read a character from the file without incrementing the pointer. More...
 
PropWare::ErrorCode get_error () const
 Get the latest error that occurred during an unsafe method call. More...
 

Static Public Attributes

static const unsigned int MAX_FILENAME_LENGTH = 32
 

Detailed Description

Read a file on a FAT 16 or FAT 32 storage device.

A file can be echoed to the terminal with a simple program such as

int main () {
const SD driver;
FatFS filesystem(&driver);
filesystem.mount();
FatFileReader reader(filesystem, "fat_test.txt");
reader.open();
while (!reader.eof())
pwOut << reader.get_char();
return 0;
}

It can also be hooked up to the PropWare::Scanner class for line-by-line or formatted reading:

int main () {
const SD driver;
FatFS filesystem(&driver);
filesystem.mount();
FatFileReader reader(filesystem, "fat_test.txt");
reader.open();
Scanner fileScanner(&reader);
char buffer[256];
while (!reader.eof()) {
fileScanner.gets(buffer, 256);
pwOut.println(buffer);
}
return 0;
}
Examples
FileReader_Demo.cpp, and FileWriter_Demo.cpp.

Definition at line 79 of file fatfilereader.h.

Member Enumeration Documentation

◆ ErrorCode

Enumerator
ENTRY_NOT_FILE 

FatFile Error 0

FILENAME_NOT_FOUND 

FatFile Error 1

Definition at line 38 of file fatfile.h.

◆ SeekDir

enum PropWare::File::SeekDir
stronginherited
Enumerator
BEG 

beginning of the stream

CUR 

current position in the stream

END 

end of the stream

Definition at line 47 of file file.h.

Constructor & Destructor Documentation

◆ FatFileReader()

PropWare::FatFileReader::FatFileReader ( FatFS fs,
const char  name[],
BlockStorage::Buffer buffer = SHARED_BUFFER,
const Printer logger = pwOut 
)

Construct a new file instance.

Parameters
[in]fsThe filesystem is needed for opening the file
[in]nameName of the file to open - it must exist in the current working directory (see issue 55 for opening from a relative or absolute path)
[in]*bufferAddress of a dedicated buffer that should be used for this file. If left as the NULL (the default), a shared buffer will be used.
[in]loggerThis is only used for printing debug statements. Use of the logger is limited such that all references will be optimized out in normal application code

Definition at line 93 of file fatfilereader.h.

Member Function Documentation

◆ close()

virtual PropWare::ErrorCode PropWare::File::close ( )
virtualinherited

Close a file - a required step in any workflow that includes opening a file.

Returns
0 upon success, error code otherwise

Definition at line 74 of file file.h.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ eof()

bool PropWare::FileReader::eof ( ) const
inherited

Determine whether the read pointer has reached the end of the file.

Returns
Returns true if the pointer points to the end of the file, false otherwise

Definition at line 75 of file filereader.h.

◆ exists() [1/2]

bool PropWare::FatFile::exists ( ) const
inherited

Determine if a file exists (file does not have to be open)

Returns
True if the file exists, false otherwise

Definition at line 62 of file fatfile.h.

+ Here is the call graph for this function:

◆ exists() [2/2]

bool PropWare::FatFile::exists ( PropWare::ErrorCode &  err) const
inherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[out]errIt is possible for an error to occur

Definition at line 72 of file fatfile.h.

+ Here is the call graph for this function:

◆ flush() [1/2]

PropWare::ErrorCode PropWare::FileReader::flush ( )
virtualinherited

Flush any modified data back to the SD card.

Returns
0 upon success, error code otherwise

Implements PropWare::File.

Definition at line 40 of file filereader.h.

◆ flush() [2/2]

virtual PropWare::ErrorCode PropWare::File::flush ( )
pure virtualinherited

Flush any modified data back to the SD card.

Returns
0 upon success, error code otherwise

Implemented in PropWare::FatFileWriter, and PropWare::FileReader.

+ Here is the caller graph for this function:

◆ get_char()

char PropWare::FileReader::get_char ( )
virtualinherited

Read a character from the file.

Postcondition
If an error occurs, you can retrieve the error code via FileReader::get_error()
Returns
Character upon success, -1 otherwise

Implements PropWare::ScanCapable.

Definition at line 60 of file filereader.h.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ get_error()

PropWare::ErrorCode PropWare::FileReader::get_error ( ) const
inherited

Get the latest error that occurred during an unsafe method call.

Methods such as FileReader::get_char() would normally throw an exception if an error occurred in a C++ program, but due to size constraints, exceptions are not used by PropWare. Therefore, any error that is occurs in a function that does not return ErrorCode simply saves the error to the internal state and returns a known value.

Returns
Most recent error code

Definition at line 115 of file filereader.h.

◆ get_name()

const char* PropWare::FatFile::get_name ( ) const
inherited

Determine the name of a file.

Returns
Character array containing the file - DO NOT modify the array, it will modify the internals of the file instance

Definition at line 53 of file fatfile.h.

+ Here is the caller graph for this function:

◆ open()

PropWare::ErrorCode PropWare::FatFileReader::open ( )
virtual

Open the file.

Returns
0 upon success, error code otherwise

Implements PropWare::File.

Definition at line 100 of file fatfilereader.h.

+ Here is the call graph for this function:

◆ peek()

char PropWare::FileReader::peek ( )
inherited

Read a character from the file without incrementing the pointer.

Postcondition
If an error occurs, you can retrieve the error code via FileReader::get_error()
Returns
Character upon success, -1 otherwise

Definition at line 99 of file filereader.h.

+ Here is the call graph for this function:

◆ safe_get_char()

PropWare::ErrorCode PropWare::FatFileReader::safe_get_char ( char c)
virtual

Read a character from the file.

Parameters
[out]cCharacter from file will be stored into c
Returns
0 upon success, error code otherwise

Implements PropWare::FileReader.

Definition at line 115 of file fatfilereader.h.

◆ safe_peek()

PropWare::ErrorCode PropWare::FileReader::safe_peek ( char c)
inherited

Read a character from the file without incrementing the pointer.

Parameters
[out]cCharacter from file will be stored into c
Returns
0 upon success, error code otherwise

Definition at line 86 of file filereader.h.

+ Here is the call graph for this function:

◆ seek() [1/2]

PropWare::ErrorCode PropWare::File::seek ( const int32_t  offset,
const SeekDir  way 
)
inherited

Sets the position of the next character to be read or written.

Parameters
[in]offsetOffset value, relative to the way parameter
[in]wayStarting position for the movement and direction of movement
Returns
0 upon success, error code otherwise

Definition at line 112 of file file.h.

+ Here is the caller graph for this function:

◆ seek() [2/2]

PropWare::ErrorCode PropWare::File::seek ( const int32_t  position)
inherited

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]positionAbsolute position to move the file position indicator

Definition at line 147 of file file.h.

+ Here is the call graph for this function:

◆ tell()

int32_t PropWare::File::tell ( ) const
inherited

Obtain the value of the file position indicator.

Postcondition
The next byte to be read from the file

Definition at line 100 of file file.h.


The documentation for this class was generated from the following file:
main
int main(void)
Definition: GraphicsTest.c:20
pwOut
PropWare::Printer pwOut
Most common use of printing in PropWare applications (not thread safe; see PropWare::pwSyncOut for mu...
PropWare::FatFileReader::FatFileReader
FatFileReader(FatFS &fs, const char name[], BlockStorage::Buffer &buffer=SHARED_BUFFER, const Printer &logger=pwOut)
Construct a new file instance.
Definition: fatfilereader.h:93
PropWare::Printer::println
void println(const char string[]) const
Print a null-terminated string followed by a newline (' ')
Definition: printer.h:599