CsvDocument/ru

Предупреждение: ЭТОТ ДОКУМЕНТ УСТАРЕЛ. CSVDOCUMENT ВХОДИТ В СОСТАВ FPC, НАЧИНАЯ С ВЕРСИИ 3.0. CCR ВЕРСИЯ БУДЕТ УПРАЗДНЕНА.

О библиотеке

Библиотека CsvDocument - это модуль Free Pascal, содержащий набор классов для работы с файлами в формате CSV. Библиотека была разработана для обмена табличными данными с OpenOffice Calc / MS Office Excel с использованием CSV в качестве промежуточного формата.

Возможности:

Чтение/запись произвольного поля с помощью объектной модели CSV-документа (класс TCSVDocument). Данный подход требует предварительной загрузки CSV-файла в память.
Последовательное чтение файла CSV (поле за полем) с помощью класса TCSVParser. Позволяет читать содержимое файла CSV напрямую, без предварительной загрузки всего файла в память.
Последовательная запись файла CSV (поле за полем) с помощью класса TCSVBuilder. Позволяет записывать содержимое документа напрямую в файл, без буферизации в памяти. Реализована в версии 0.4 и выше.
Реализация CSV совместима с реализацией в OpenOffice Calc / MS Office Excel, т.е. CSV-файлы, сохранённые из Calc/Excel, можно читать с помощью CsvDocument, и наоборот.
Поддерживается как кодировка UTF-8, так и кодовые страницы windows-xxx. Библиотека использует тип string для всех строковых операций и сама не осуществляет каких-либо преобразований. Следует помнить, что Excel не поддерживает CSV-файлы в кодировке UTF-8.
Поддержка переводов строки внутри полей CSV. В том числе из-за этого пришлось изобретать велосипед. Следует помнить, что из пары OO Calc / MS Excel переводы строки в полях поддерживает только Calc.
Доступ к полям по аналогии с компонентом StringGrid: TCsvDocument.Cells[ACol, ARow]. Доступ к полям безопасен, т.е. при чтении несуществующего поля возвращается пустая строка, а не вызывается исключение типа "Index out of bounds". Для того, чтобы отличить пустое поле от несуществующего, можно воспользоваться методами HasRow/HasCell и свойствами RowCount/ColCount.
Поддержка поиска по строке/столбцу с помощью методов IndexOfRow(AString, ACol) / IndexOfCol(AString, ARow). Реализована в версии 0.3 и выше.
Нет искусственных ограничений на длину поля, число строк/столбцов, и т.д. Естественные ограничения сохраняются: производительность системы, объём свободной памяти, ограничение в 2 Гб на длину строки типа string, и ограничение на максимальное значение 32-разрядного знакового целого типа.
Соответствие RFC 4180 (http://tools.ietf.org/html/rfc4180#section-2) при использовании настроек по умолчанию. Реализовано в версии 0.4 и выше.
Соответствие неофициальной спецификации формата CSV (http://www.creativyst.com/Doc/Articles/CSV/CSV01.htm#FileFormat). Реализовано в версии 0.3 и выше. Начиная с версии 0.4, требует установки свойства IgnoreOuterWhitespace в True.

Автор

Владимир Жиров

Участники, внесшие вклад в развитие библитеки

Luiz Américo Pereira Câmara

Mattias Gärtner

Reinier Olislagers

Лицензия

Modified LGPL (та же, что у FPC RTL и Lazarus LCL).

Зависимости

Библиотека представляет собой один файл с исходным кодом и зависит только от FPC RTL и FCL.

Изменения

Версия 0.1 (22.01.2010)

первый выпуск

Версия 0.2 (31.05.2010)

исправлено некорректное преобразование символов конца строки
исправлена компиляция со включенными проверками диапазона (Range checks)
стала доступна функция QuoteCSVString, упрощающая генерацию CSV без использования класса TCsvDocument
выполнена небольшая чистка кода

Версия 0.3 (14.01.2011)

изменён API CsvParser: callback-методы заменены на пару методов ResetParser/ParseNextCell, чтобы библиотеку можно было использовать без создания вспомогательных классов. Пример использования нового API можно посмотреть в методе TCSVDocument.LoadFromStream.
изменён API CsvDocument: метод TrimEmptyCells переименован в RemoveTrailingEmptyCells.
поддерживается удаление пробельных символов в начале и конце поля. Добавлено новое свойство TrimWhitespace. Внимание: TrimWhitespace по умолчанию включено.
поддерживается поиск по строке/столбцу с помощью методов IndexOfRow(AString, ACol) / IndexOfCol(AString, ARow)
улучшена производительность
выполнена чистка кода
добавлен набор простых тестов

Версия 0.4 (10.05.2011)

функция QuoteCSVString заменена классом TCSVBuilder. Пример его использования можно посмотреть в методе TCSVDocument.SaveToStream.
свойство TrimWhitespace переименовано в IgnoreOuterWhitespace (для единообразия с новым свойством QuoteOuterWhitespace).
поддержка одинакового числа столбцов во всём документе (требуется для соответствия RFC 4180). См. свойство EqualColCountPerRow.
настройки по умолчанию изменены на соответствующие RFC 4180 (Delimiter - запятая, QuoteChar - двойная кавычка, окончания строк - CRLF, удаление пробельных символов в начале и конце поля выключено, одинаковое число столбцов во всём документе включено).
реализовано преобразование окончаний строк, включенных в содержимое полей, при разборе и генерации CSV-файла. Это позволяет избежать смешения различных окончаний строк в выходном файле при использовании принятых в ОС окончаний строк и работе с одним и тем же документом под разными ОС.
параметры формата CSV перемещены в класс TCSVHandler (предка классов TCSVParser, TCSVBuilder и TCSVDocument).
набор тестов обновлён для соответствия RFC 4180.
исправлены мелкие недоработки в demo-приложении.
включен оптимизированный вариант функции ChangeLineEndings, созданный Mattias Gärtner.
оптимизации по скорости, улучшения в demo-приложении и пакет для Lazarus от Luiz Américo Pereira Câmara.

Версия 0.5 (25.10.2014)

исправлена ошибка в методе TrimEmptyCells, метод удалял пустые ячейки не только в конце, но и в середине строки (патч от Reinier Olislagers)
добавлено свойство TCSVParser.MaxColCount: максимальное число столбцов, определяемое в процессе чтения CSV-файла (патч от Reinier Olislagers)
добавлены комментарии к процедурам, функциям и свойствам (на основе патча от Reinier Olislagers)
исправления в demo-приложении (обновление интерфейса после загрузки документа, отдельные файлы проекта для Lazarus 0.9.30)

Статус

Beta

Загрузка

Новый выпуск библиотеки можно загрузить с Lazarus-CCR или Bitbucket:

http://sourceforge.net/projects/lazarus-ccr/files/CsvDocument/CsvDocument%200.5/csvdocument-0.5.zip/download

https://bitbucket.org/vvzh/csvdocument/downloads/csvdocument-0.5.zip

Архив содержит саму библиотеку, демонстрационное приложение и набор тестов.

Разрабатываемую версию можно получить:

Из Mercurial-репозитория на Bitbucket:

  hg clone https://bitbucket.org/vvzh/csvdocument csvdocument

Из Subversion-репозитория Lazarus-CCR:

  svn co svn://svn.code.sf.net/p/lazarus-ccr/svn/components/csvdocument csvdocument

Установка и использование

Достаточно добавить модуль CsvDocument в секцию uses. Если необходимо, можно установить путь к модулю в свойствах проекта. Другой вариант:

1. Откройте файл "csvdocument_package.lpk" из Lazarus IDE, используя меню: "Пакет -> Открыть файл пакета (.lpk) ...".

2. Скомпилируйте пакет.

3. Откройте ваш проект.

4. Добавьте пакет в качестве зависимости для вашего проекта с помощью Инспектора проекта.

Обратная связь

Просьба отправлять сообщения об ошибках и патчи по адресу, указанному в исходном коде библиотеки.

См. также