Kea  2.3.5-git
isc::util::CSVFile Class Reference

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. More...
 
virtual ~CSVFile ()
 Destructor. More...
 
void addColumn (const std::string &col_name)
 Adds new column name. More...
 
void append (const CSVRow &row) const
 Writes the CSV row into the file. More...
 
void close ()
 Closes the CSV file. More...
 
bool exists () const
 Checks if the CSV file exists and can be opened for reading. More...
 
void flush () const
 Flushes a file. More...
 
size_t getColumnCount () const
 Returns the number of columns in the file. More...
 
size_t getColumnIndex (const std::string &col_name) const
 Returns the index of the column having specified name. More...
 
std::string getColumnName (const size_t col_index) const
 Returns the name of the column. More...
 
std::string getFilename () const
 Returns the path to the CSV file. More...
 
std::string getReadMsg () const
 Returns the description of the last error returned by the CSVFile::next function. More...
 
bool next (CSVRow &row, const bool skip_validation=false)
 Reads next row from CSV file. More...
 
virtual void open (const bool seek_to_end=false)
 Opens existing file or creates a new one. More...
 
virtual void recreate ()
 Creates a new CSV file. More...
 
void setReadMsg (const std::string &read_msg)
 Sets error message after row validation. More...
 

Static Public Member Functions

static CSVRow EMPTY_ROW ()
 Represents empty row. More...
 

Protected Member Functions

void addColumnInternal (const std::string &col_name)
 Adds a column regardless if the file is open or not. More...
 
virtual bool validate (const CSVRow &row)
 Validate the row read from a file. More...
 
virtual bool validateHeader (const CSVRow &header)
 This function validates the header of the CSV file. More...
 

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
filenameCSV 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_nameName of the column.
Exceptions
CSVFileErrorif 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_nameName of the column.
Exceptions
CSVFileErrorif 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
rowObject representing a CSV file row.
Exceptions
CSVFileErrorWhen 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(), isc::util::CSVRow::getValuesCount(), isc_throw, and isc::util::CSVRow::render().

+ 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 open(), recreate(), and ~CSVFile().

◆ 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(), and 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.

Referenced by isc::lfc::LFCController::launch(), and isc::dhcp::Memfile_LeaseMgr::lfcCallback().

◆ flush()

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

Flushes a file.

Definition at line 141 of file csv_file.cc.

◆ getColumnCount()

◆ 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_nameName of the column.
Returns
Index of the column.
Exceptions
OutOfRangeif 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(), isc::dhcp::CSVLeaseFile6::next(), isc::dhcp::CSVLeaseFile4::next(), 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_indexIndex of the column.
Returns
Name of the column.
Exceptions
CSVFileErrorif the specified index is out of range.

Definition at line 247 of file csv_file.cc.

References isc_throw.

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

◆ getFilename()

◆ 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]rowObject receiving the parsed CSV file.
skip_validationDo 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(), isc::util::CSVRow::parse(), setReadMsg(), validate(), and isc::Exception::what().

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_endA boolean value which indicates if the input and output file pointer should be set at the end of file.
Exceptions
CSVFileErrorwhen IO operation fails.

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

Definition at line 302 of file csv_file.cc.

References addColumnInternal(), close(), getColumnCount(), getReadMsg(), isc::util::CSVRow::getValuesCount(), isc_throw, next(), isc::util::CSVRow::readAt(), 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, isc::Exception::what(), and isc::util::CSVRow::writeAt().

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_msgError message to be set.

Definition at line 486 of file csv_file.h.

Referenced by isc::util::VersionedCSVFile::columnCountError(), isc::dhcp::CSVLeaseFile6::next(), isc::dhcp::CSVLeaseFile4::next(), isc::util::VersionedCSVFile::next(), 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
rowA row to be validated.
Returns
true if the column is valid; false otherwise.

Definition at line 401 of file csv_file.cc.

References getColumnCount(), isc::util::CSVRow::getValuesCount(), 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
headerA 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(), getColumnName(), isc::util::CSVRow::getValuesCount(), and isc::util::CSVRow::readAt().

Referenced by open().

+ Here is the call graph for this function:

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