console/kabcclient

CSVTemplate Class Reference

#include <csvtemplate.h>

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.krammer@gmx.at>

See also:: CSVTemplateFactory

Definition at line 88 of file csvtemplate.h.


Public Member Functions
int	columns () const
	CSVTemplate (KConfigBase *config)
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 ()

Constructor & Destructor Documentation

CSVTemplate::CSVTemplate ( KConfigBase * config )

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 initalizes 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:

console/kabcclient

CSVTemplate Class Reference

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

console/kabcclient

kdepim