CSVTemplate Class Reference

#include <csvtemplate.h>

Public Member Functions
	CSVTemplate (KConfigBase *config)
int	columns () const
const QString &	delimiter () const
QString	fieldText (int column, const KABC::Addressee &addressee) const
const QString &	quote () const
void	setFieldText (int column, KABC::Addressee &addressee, const QString &text) const

Static Public Member Functions
static CSVTemplate *	defaultTemplate ()

Detailed Description

Class for handling KAddressBook's CSV templates.

Reads the template's column mapping and configuration like quoting and delimiter from a KConfigBase object that has parsed the template's .desktop file.

The instance can then be used to get or set the value of a addressee field based on the column index of the target CSV format.

Example: Creating a CSV line from an addressee object based on a template. Using the default template instead of creating one. See CSVTemplateFactory for an easy way to do that.

QString line;

CSVTemplate* template = CSVTemplate::defaultTemplate();

for (int col = 0; i < template->columns(); ++i)
{
    line += template->quote(); // start quoting of the field

    line += template->fieldText(col, addressee); // add the text value

    line += template->quote(); // end quoting of the field

    // add delimiter if not at end of the CSV line
    if (col < (template->columns() - 1))
        line += template->delimiter();
}

Example: Filling an addressee instance from a line of a CSV file. Assuming for simplicity that there is no quoting.

KABC::Addressee addressee;

// as we assumed absence of quoting, we can use QStringList::split()
// to separate the fields. Using @c true for allowEmptyEntries to make sure
// we do not miss any empty fields
QStringList fields = QStringList::split(template->delimiter(), line, true);

// iterate over the fields and let the template parse the text
QStringList::const_iterator it = fields.begin();
for (int col = 0; it != fields.end(); ++it, ++col)
{
    template->setFieldText(col, addressee, *it);
}

Author

Kevin Krammer, kevin.nosp@m..kra.nosp@m.mmer@.nosp@m.gmx..nosp@m.at

See also

CSVTemplateFactory

Definition at line 88 of file csvtemplate.h.

Constructor & Destructor Documentation

CSVTemplate::CSVTemplate ( KConfigBase *  config )

explicit

Creates a template handler for the given description.

Assuming that the best way to read the actual template description files is using KConfigBase derived classes, this constructor initializes a template handler from such an instance.

See also

Handling of CSV (comma separated values) input/output

Definition at line 41 of file csvtemplate.cpp.

Member Function Documentation

int CSVTemplate::columns ( ) const

inline

Returns the number of CSV columns.

The returned value is taken from the "Columns" entry of group "General" of the CSV template.

It can be greater than the number of specified column<->field mappings for example for templates that only parse parts of a larger CSV format.

Returns

the number of columns of the CSV format

Definition at line 113 of file csvtemplate.h.

CSVTemplate * CSVTemplate::defaultTemplate ( )

static

Returns the template with default setup.

The default template contains a mapping for almost all fields of the KABC::Addressee, it just leaves formatted name out, i.e. column 0 will be the family name, column 1 will be the given name, and so on.

The quote character will be double quote and the delimiter the comma.

Dateformat spec is "Y-M-D", thus resembling the format specified for ISO-8601 (e.g. 2005-10-31)

Note

There will only be one instance of this template, i.e. defaultTemplate() is like a singleton

Returns

the default CSV template

Definition at line 429 of file csvtemplate.cpp.

const QString& CSVTemplate::delimiter ( ) const

inline

Returns the CSV delimiter string.

The delimiter is usually only one character, e.g comma, semicolon, etc. However the delimiter can also be the value of an entry in the CSV template and thus theoretially be longer.

Note

The delimiter could appear inside CSV columns if the column text is inside quotes. See quote()

The actual value is determined based on the "DelimiterType" entry of group "General" of the CSV template:

• value 0: comma ','
• value 1: semicolon ';'
• value 2: tab character '\t'
• value 3: space ' '
• value 4: value of the "DelimiterOther" entry of the same group

Returns

the delimiter string of the CSV format

Definition at line 135 of file csvtemplate.h.

QString CSVTemplate::fieldText	(	int	column,
		const KABC::Addressee &	addressee
	)		const

Returns the specified field of the given addressee formatted as a string.

Uses the column to field index mapping specified in the group "csv column map" to determine the addressee field. Converts the field's datatype to a string representation if necessary, e.g. a date string according to the CSV format's date format spec.

In case of a date the value of the "DatePattern" entry of group "General" is used as a hint how the date is supposed to look in the CSV data.

Note

If the text contains the delimiter() string it will need to be quoted.

Parameters

column	the CSV column the text is for
addressee	the addressbook entry to take the data from

Returns

text representation of the specified addressee field's value. Can be QString() if the column is not mapped or the addressee or field is empty

See also

setFieldText()

quote()

Handling of CSV (comma separated values) input/output

Definition at line 113 of file csvtemplate.cpp.

const QString& CSVTemplate::quote ( ) const

inline

Returns the CSV quoting string.

Quoting can be necessary if a CSV column text can potentially contain the delimiter character/string. For example

one,"two,2",three

would be three columns if the CSV format's quoting character is the double quote character but four columns if it is single quote character or if the template doesn't specify a quoting character.

The actual value is determined based on the "QuoteType" entry of group "General" of the CSV template:

• value 0: double quote "
• value 1: single quote '
• value 2: no quoting

Returns

the quoting character/string. Can be QString()

See also

delimiter()

Definition at line 160 of file csvtemplate.h.

void CSVTemplate::setFieldText	(	int	column,
		KABC::Addressee &	addressee,
		const QString &	text
	)		const

Sets an addressee field using the data of a given text.

Uses the column to field index mapping specified in the group "csv column map" to determine the addressee field. Converts the string representation to the field's datatype to if necessary, e.g. parsing a date string according to the CSV format's date format spec.

In case of a date the value of the "DatePattern" entry of group "General" is used as a hint how the date is supposed to look in the CSV data, i.e. which part of the string should be parsed as which date value.

Note

The string is expected without any quoting characters. See quote()

Parameters

column	the CSV column the text is from. If there is no mapping for this column, it will just return
addressee	the addressbook entry to put the data into
text	the data from the CSV line

See also

fieldText()

Handling of CSV (comma separated values) input/output

Definition at line 255 of file csvtemplate.cpp.

---

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

• csvtemplate.h
• csvtemplate.cpp