Provides input/output access to CSV files. More...

#include <csv_file.h>

Inheritance diagram for isc::util::CSVFile:

Public Member Functions
	CSVFile (const std::string &filename)
	Constructor.

virtual	~CSVFile ()
	Destructor.

void	addColumn (const std::string &col_name)
	Adds new column name.

void	append (const CSVRow &row) const
	Writes the CSV row into the file.

void	close ()
	Closes the CSV file.

bool	exists () const
	Checks if the CSV file exists and can be opened for reading.

void	flush () const
	Flushes a file.

size_t	getColumnCount () const
	Returns the number of columns in the file.

size_t	getColumnIndex (const std::string &col_name) const
	Returns the index of the column having specified name.

std::string	getColumnName (const size_t col_index) const
	Returns the name of the column.

std::string	getFilename () const
	Returns the path to the CSV file.

std::string	getReadMsg () const
	Returns the description of the last error returned by the `CSVFile::next` function.

bool	next (CSVRow &row, const bool skip_validation=false)
	Reads next row from CSV file.

virtual void	open (const bool seek_to_end=false)
	Opens existing file or creates a new one.

virtual void	recreate ()
	Creates a new CSV file.

void	setReadMsg (const std::string &read_msg)
	Sets error message after row validation.

Static Public Member Functions
static CSVRow	EMPTY_ROW ()
	Represents empty row.

Protected Member Functions
void	addColumnInternal (const std::string &col_name)
	Adds a column regardless if the file is open or not.

virtual bool	validate (const CSVRow &row)
	Validate the row read from a file.

virtual bool	validateHeader (const CSVRow &header)
	This function validates the header of the CSV file.

Detailed Description

Provides input/output access to CSV files.

This class provides basic methods to access (parse) and create CSV files. The file is identified by its name qualified with the absolute path. The name of the file is passed to the constructor. Constructor doesn't open/create a file, but simply records a file name specified by a caller.

There are two functions that can be used to open a file:

open - opens an existing file; if the file doesn't exist it creates it,
recreate - removes existing file and creates a new one.

When the file is opened its header file is parsed and column names are identified. At this point it is already possible to get the list of the column names using appropriate accessors. The data rows are not parsed at this time. The row parsing is triggered by calling next function. The result of parsing a row is stored in the CSVRow object passed as a parameter.

When the new file is created (when recreate is called), the CSV header is immediately written into it. The header consists of the column names specified with the addColumn function. The subsequent rows are written into this file by calling append.

Definition at line 358 of file csv_file.h.

Constructor & Destructor Documentation

◆ CSVFile()

isc::util::CSVFile::CSVFile ( const std::string & filename )

Constructor.

Parameters

filename CSV file name.

Definition at line 114 of file csv_file.cc.

◆ ~CSVFile()

isc::util::CSVFile::~CSVFile ( )

virtual

Destructor.

Definition at line 118 of file csv_file.cc.

References close().

Here is the call graph for this function:

Member Function Documentation

◆ addColumn()

void isc::util::CSVFile::addColumn ( const std::string & col_name )

Adds new column name.

This column adds a new column but doesn't write it to the file yet. The name of the column will be placed in the CSV header when new file is created by calling recreate or open function.

Parameters

col_name Name of the column.

Exceptions

CSVFileError if a column with the specified name exists.

Definition at line 147 of file csv_file.cc.

References addColumnInternal(), getFilename(), and isc_throw.

Referenced by isc::util::VersionedCSVFile::addColumn().

Here is the call graph for this function:

◆ addColumnInternal()

void isc::util::CSVFile::addColumnInternal ( const std::string & col_name )

protected

Adds a column regardless if the file is open or not.

This function adds as new column to the collection. It is meant to be called internally by the methods of the base class and derived classes. It must not be used in the public scope. The CSVFile::addColumn must be used in the public scope instead, because it prevents addition of the new column when the file is open.

Parameters

col_name Name of the column.

Exceptions

CSVFileError if a column with the specified name exists.

Definition at line 158 of file csv_file.cc.

References isc_throw.

Referenced by addColumn(), and open().

◆ append()

void isc::util::CSVFile::append ( const CSVRow & row ) const

Writes the CSV row into the file.

Parameters

row	Object representing a CSV file row.

Exceptions

CSVFileError When error occurred during IO operation or if the size of the row doesn't match the number of columns.

Todo: Apparently, seekp and seekg are interchangeable. A call to seekp results in moving the input pointer too. This is ok for now. It means that when the append() is called, the read pointer is moved to the EOF. For the current use cases we only read a file and then append a new content. If we come up with the scenarios when read and write is needed at the same time, we may revisit this: perhaps remember the old pointer. Also, for safety, we call both functions so as we are sure that both pointers are moved.

Definition at line 167 of file csv_file.cc.

References getColumnCount(), and isc_throw.

Here is the call graph for this function:

◆ close()

void isc::util::CSVFile::close ( )

Closes the CSV file.

Definition at line 123 of file csv_file.cc.

Referenced by ~CSVFile(), open(), and recreate().

◆ EMPTY_ROW()

static CSVRow isc::util::CSVFile::EMPTY_ROW ( )

inlinestatic

Represents empty row.

Definition at line 491 of file csv_file.h.

Referenced by isc::util::VersionedCSVFile::next(), next(), isc::dhcp::CSVLeaseFile4::next(), and isc::dhcp::CSVLeaseFile6::next().

◆ exists()

bool isc::util::CSVFile::exists ( ) const

Checks if the CSV file exists and can be opened for reading.

This method doesn't check if the existing file has a correct file format.

Returns: true if file exists, false otherwise.

Definition at line 133 of file csv_file.cc.

◆ flush()

void isc::util::CSVFile::flush ( ) const

Flushes a file.

Definition at line 141 of file csv_file.cc.

◆ getColumnCount()

size_t isc::util::CSVFile::getColumnCount ( ) const

inline

Returns the number of columns in the file.

Definition at line 403 of file csv_file.h.

Referenced by append(), isc::dhcp::CSVLeaseFile4::append(), isc::dhcp::CSVLeaseFile6::append(), isc::util::VersionedCSVFile::getSchemaVersion(), isc::util::VersionedCSVFile::getVersionedColumn(), isc::util::VersionedCSVFile::next(), open(), isc::util::VersionedCSVFile::open(), recreate(), isc::util::VersionedCSVFile::recreate(), validate(), validateHeader(), and isc::util::VersionedCSVFile::validateHeader().

◆ getColumnIndex()

size_t isc::util::CSVFile::getColumnIndex ( const std::string & col_name ) const

Returns the index of the column having specified name.

This function is exception safe.

Parameters

col_name Name of the column.

Returns: Index of the column.

Exceptions

OutOfRange if column with such name doesn't exist.

Definition at line 237 of file csv_file.cc.

References isc_throw.

Referenced by isc::dhcp::CSVLeaseFile4::append(), isc::dhcp::CSVLeaseFile6::append(), and isc::util::VersionedCSVFile::setMinimumValidColumns().

◆ getColumnName()

std::string isc::util::CSVFile::getColumnName ( const size_t col_index ) const

Returns the name of the column.

Parameters

col_index Index of the column.

Returns: Name of the column.

Exceptions

CSVFileError if the specified index is out of range.

Definition at line 247 of file csv_file.cc.

References isc_throw.

Referenced by recreate(), validateHeader(), and isc::util::VersionedCSVFile::validateHeader().

◆ getFilename()

std::string isc::util::CSVFile::getFilename ( ) const

inline

Returns the path to the CSV file.

Definition at line 408 of file csv_file.h.

Referenced by addColumn(), isc::util::VersionedCSVFile::columnCountError(), isc::util::VersionedCSVFile::getVersionedColumn(), isc::util::VersionedCSVFile::open(), and isc::util::VersionedCSVFile::recreate().

◆ getReadMsg()

std::string isc::util::CSVFile::getReadMsg ( ) const

inline

Returns the description of the last error returned by the CSVFile::next function.

Returns: Description of the last error during row validation.

Definition at line 416 of file csv_file.h.

Referenced by open().

◆ next()

bool isc::util::CSVFile::next	(	CSVRow &	row,
		const bool	skip_validation = false )

Reads next row from CSV file.

This function will return the CSVRow object representing a parsed row if parsing is successful. If the end of file has been reached, the empty row is returned (a row containing no values).

Parameters

[out]	row	Object receiving the parsed CSV file.
	skip_validation	Do not perform validation.

Returns: true if row has been read and validated; false if validation failed.

Definition at line 257 of file csv_file.cc.

References EMPTY_ROW(), setReadMsg(), and validate().

Referenced by isc::util::VersionedCSVFile::next(), and open().

Here is the call graph for this function:

◆ open()

void isc::util::CSVFile::open ( const bool seek_to_end = false )

virtual

Opens existing file or creates a new one.

This function will try to open existing file if this file has size greater than 0. If the file doesn't exist or has size of 0, the file is recreated. If the existing file has been opened, the header is parsed and column names are initialized in the CSVFile object. By default, the data pointer in the file is set to the beginning of the first row. In order to retrieve the row contents the next function should be called. If a seek_to_end parameter is set to true, the file will be opened and the internal pointer will be set to the end of file.

Parameters

seek_to_end A boolean value which indicates if the input and output file pointer should be set at the end of file.

Exceptions

CSVFileError when IO operation fails.

Reimplemented in isc::dhcp::CSVLeaseFile4, isc::dhcp::CSVLeaseFile6, and isc::util::VersionedCSVFile.

Definition at line 302 of file csv_file.cc.

References addColumnInternal(), close(), getColumnCount(), getReadMsg(), isc_throw, next(), recreate(), and validateHeader().

Referenced by isc::util::VersionedCSVFile::open().

Here is the call graph for this function:

◆ recreate()

void isc::util::CSVFile::recreate ( )

virtual

Creates a new CSV file.

The file creation will fail if there are no columns specified. Otherwise, this function will write the header to the file. In order to write rows to opened file, the append function should be called.

Reimplemented in isc::util::VersionedCSVFile.

Definition at line 370 of file csv_file.cc.

References close(), getColumnCount(), getColumnName(), isc_throw, and isc::Exception::what().

Referenced by open(), and isc::util::VersionedCSVFile::recreate().

Here is the call graph for this function:

◆ setReadMsg()

void isc::util::CSVFile::setReadMsg ( const std::string & read_msg )

inline

Sets error message after row validation.

The CSVFile::validate function is responsible for setting the error message after validation of the row read from the CSV file. It will use this function to set this message. Note, that the validate function can set a message after successful validation too. Such message could say "success", or something similar.

Parameters

read_msg Error message to be set.

Definition at line 486 of file csv_file.h.

Referenced by isc::util::VersionedCSVFile::columnCountError(), isc::util::VersionedCSVFile::next(), next(), isc::dhcp::CSVLeaseFile4::next(), isc::dhcp::CSVLeaseFile6::next(), validate(), and isc::util::VersionedCSVFile::validateHeader().

◆ validate()

bool isc::util::CSVFile::validate ( const CSVRow & row )

protectedvirtual

Validate the row read from a file.

This function implements a basic validation for the row read from the CSV file. It is virtual so as it may be customized in derived classes.

This default implementation checks that the number of values in the row corresponds to the number of columns specified for this file.

If row validation fails, the error message is noted and can be retrieved using CSVFile::getReadMsg. The function which overrides this base implementation is responsible for setting the error message using CSVFile::setReadMsg.

Parameters

row	A row to be validated.

Returns: true if the column is valid; false otherwise.

Definition at line 401 of file csv_file.cc.

References getColumnCount(), and setReadMsg().

Referenced by next().

Here is the call graph for this function:

◆ validateHeader()

bool isc::util::CSVFile::validateHeader ( const CSVRow & header )

protectedvirtual

This function validates the header of the CSV file.

If there are any columns added to the CSVFile object, it will compare that they exactly match (including order) the header read from the file.

This function is called internally by CSVFile::open. Derived classes may add extra validation steps.

Parameters

header A row holding a header.

Returns: true if header matches the columns; false otherwise.

Reimplemented in isc::util::VersionedCSVFile.

Definition at line 415 of file csv_file.cc.

References getColumnCount(), and getColumnName().

Referenced by open().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CSVFile()

◆ ~CSVFile()

Member Function Documentation

◆ addColumn()

◆ addColumnInternal()

◆ append()

◆ close()

◆ EMPTY_ROW()

◆ exists()

◆ flush()

◆ getColumnCount()

◆ getColumnIndex()

◆ getColumnName()

◆ getFilename()

◆ getReadMsg()

◆ next()

◆ open()

◆ recreate()

◆ setReadMsg()

◆ validate()

◆ validateHeader()