Kea: isc::util::CSVFile Class Reference

| Kea 3.0.0

isc::util::CSVFile Class Reference

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

`#include <csv_file.h>`

Inheritance diagram for isc::util::CSVFile:
[legend]

## 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.

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

## ◆ ~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(), and isc::radius::RadiusAccounting::storeToFile().

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(), isc::util::CSVRow::getValuesCount(), isc_throw, and isc::util::CSVRow::render().

Referenced by isc::dhcp::CSVLeaseFile4::append(), isc::dhcp::CSVLeaseFile6::append(), and isc::radius::RadiusAccounting::storeToFile().

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(), recreate(), and isc::radius::RadiusAccounting::storeToFile().

## ◆ EMPTY_ROW()

CSVRow isc::util::CSVFile::EMPTY_ROW | ( |  | ) |
| inlinestatic

Represents empty row.

Definition at line 491 of file csv_file.h.

Referenced by isc::radius::RadiusAccounting::loadFromFile(), isc::dhcp::CSVLeaseFile4::next(), isc::dhcp::CSVLeaseFile6::next(), next(), and isc::util::VersionedCSVFile::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::radius::RadiusAccounting::storeToFile().

## ◆ 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 isc::dhcp::CSVLeaseFile4::append(), isc::dhcp::CSVLeaseFile6::append(), append(), isc::util::VersionedCSVFile::getSchemaVersion(), isc::util::VersionedCSVFile::getVersionedColumn(), isc::util::VersionedCSVFile::next(), open(), isc::util::VersionedCSVFile::open(), recreate(), isc::util::VersionedCSVFile::recreate(), isc::radius::RadiusAccounting::storeToFile(), 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(), isc::util::VersionedCSVFile::setMinimumValidColumns(), and isc::radius::RadiusAccounting::storeToFile().

## ◆ 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(), 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_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::util::CSVRow::getValuesCount(), isc_throw, next(), isc::util::CSVRow::readAt(), recreate(), and validateHeader().

Referenced by isc::util::VersionedCSVFile::open(), and isc::radius::RadiusAccounting::storeToFile().

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::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_msg | Error message to be set.

Definition at line 486 of file csv_file.h.

Referenced by isc::util::VersionedCSVFile::columnCountError(), isc::dhcp::CSVLeaseFile4::next(), isc::dhcp::CSVLeaseFile6::next(), next(), isc::util::VersionedCSVFile::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(), 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

  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(), 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:

- csv_file.h
- csv_file.cc