Difference between revisions of "CsvDocument/ru"

From Lazarus wiki
Jump to navigationJump to search
(* added category)
(page update for version 0.4)
Line 6: Line 6:
 
Возможности:
 
Возможности:
  
* Последовательное чтение CSV файла (поле за полем) с помощью класса TCSVParser. Не очень удобно, зато позволяет экономить память при обработке больших файлов.
+
* Чтение/запись произвольного поля с помощью объектной модели CSV-документа (класс TCSVDocument). Данный подход требует предварительной загрузки CSV-файла в память.
* Чтение/запись произвольного поля с помощью класса TCsvDocument. Данный подход основан на объектной модели документа, поэтому требует больше памяти.
+
* Последовательное чтение файла CSV (поле за полем) с помощью класса TCSVParser. Позволяет читать содержимое файла CSV напрямую, без предварительной загрузки всего файла в память.
 +
* Последовательная запись файла CSV (поле за полем) с помощью класса TCSVBuilder. Позволяет записывать содержимое документа напрямую в файл, без буферизации в памяти. Реализована в версии 0.4 и выше.
 
* Реализация CSV совместима с реализацией в OpenOffice Calc / MS Office Excel, т.е. CSV-файлы, сохранённые из Calc/Excel, можно читать с помощью CsvDocument, и наоборот.
 
* Реализация CSV совместима с реализацией в OpenOffice Calc / MS Office Excel, т.е. CSV-файлы, сохранённые из Calc/Excel, можно читать с помощью CsvDocument, и наоборот.
 
* Поддерживается как кодировка UTF-8, так и кодовые страницы windows-xxx. Библиотека использует тип ''string'' для всех строковых операций и сама не осуществляет каких-либо преобразований. Следует помнить, что Excel не поддерживает CSV-файлы в кодировке UTF-8.
 
* Поддерживается как кодировка UTF-8, так и кодовые страницы windows-xxx. Библиотека использует тип ''string'' для всех строковых операций и сама не осуществляет каких-либо преобразований. Следует помнить, что Excel не поддерживает CSV-файлы в кодировке UTF-8.
 
* Поддержка переводов строки внутри полей CSV. В том числе из-за этого пришлось изобретать велосипед. Следует помнить, что из пары OO Calc / MS Excel переводы строки в полях поддерживает только Calc.
 
* Поддержка переводов строки внутри полей CSV. В том числе из-за этого пришлось изобретать велосипед. Следует помнить, что из пары OO Calc / MS Excel переводы строки в полях поддерживает только Calc.
 
* Доступ к полям по аналогии с компонентом StringGrid: TCsvDocument.Cells[ACol, ARow]. Доступ к полям безопасен, т.е. при чтении несуществующего поля возвращается пустая строка, а не вызывается исключение типа "Index out of bounds". Для того, чтобы отличить пустое поле от несуществующего, можно воспользоваться методами HasRow/HasCell и свойствами RowCount/ColCount.
 
* Доступ к полям по аналогии с компонентом StringGrid: TCsvDocument.Cells[ACol, ARow]. Доступ к полям безопасен, т.е. при чтении несуществующего поля возвращается пустая строка, а не вызывается исключение типа "Index out of bounds". Для того, чтобы отличить пустое поле от несуществующего, можно воспользоваться методами HasRow/HasCell и свойствами RowCount/ColCount.
 +
* Поддержка поиска по строке/столбцу с помощью методов IndexOfRow(AString, ACol) / IndexOfCol(AString, ARow). Реализована в версии 0.3 и выше.
 
* Нет искусственных ограничений на длину поля, число строк/столбцов, и т.д. Естественные  ограничения сохраняются: производительность системы, объём свободной памяти, ограничение в 2 Гб на длину строки типа ''string'', и ограничение на максимальное значение 32-разрядного знакового целого типа.
 
* Нет искусственных ограничений на длину поля, число строк/столбцов, и т.д. Естественные  ограничения сохраняются: производительность системы, объём свободной памяти, ограничение в 2 Гб на длину строки типа ''string'', и ограничение на максимальное значение 32-разрядного знакового целого типа.
* Для версии 0.3 и выше - соответствие неофициальной спецификации формата CSV http://www.creativyst.com/Doc/Articles/CSV/CSV01.htm
+
* Соответствие 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
  
 
=== Лицензия ===
 
=== Лицензия ===
[http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL modified] [http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL LGPL] (та же, что у FPC RTL и Lazarus LCL).
+
[http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL Modified] [http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL LGPL] (та же, что у FPC RTL и Lazarus LCL).
  
 
=== Зависимости ===
 
=== Зависимости ===
Line 33: Line 40:
 
* выполнена небольшая чистка кода
 
* выполнена небольшая чистка кода
 
==== Версия 0.3 (14.01.2011) ====
 
==== Версия 0.3 (14.01.2011) ====
* изменён API CsvParser: callback-методы заменены на пару методов ResetParser/ParseNextCell, чтобы библиотеку можно было использовать в функциональных программах (без объявления объектов). Пример использования нового API можно посмотреть в TCSVDocument.LoadFromStream.
+
* изменён API CsvParser: callback-методы заменены на пару методов ResetParser/ParseNextCell, чтобы библиотеку можно было использовать в функциональных программах (без объявления объектов). Пример использования нового API можно посмотреть в методе TCSVDocument.LoadFromStream.
* изменён API CsvDocument: метод TrimEmptyCells переименован в RemoveTrailingEmptyCells
+
* изменён API CsvDocument: метод TrimEmptyCells переименован в RemoveTrailingEmptyCells.
 
* поддерживается удаление пробельных символов в начале и конце поля. Добавлено новое свойство TrimWhitespace. '''Внимание''': TrimWhitespace по умолчанию включено.
 
* поддерживается удаление пробельных символов в начале и конце поля. Добавлено новое свойство TrimWhitespace. '''Внимание''': TrimWhitespace по умолчанию включено.
 
* поддерживается поиск по строке/столбцу с помощью методов IndexOfRow(AString, ACol) / IndexOfCol(AString, ARow)
 
* поддерживается поиск по строке/столбцу с помощью методов IndexOfRow(AString, ACol) / IndexOfCol(AString, ARow)
Line 40: Line 47:
 
* выполнена чистка кода
 
* выполнена чистка кода
 
* добавлен набор простых тестов
 
* добавлен набор простых тестов
 +
==== Версия 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.
  
 
=== Статус ===
 
=== Статус ===
Line 45: Line 63:
  
 
=== Загрузка ===
 
=== Загрузка ===
Последнюю версию можно загрузить с lazarus-ccr:
+
Новый выпуск библиотеки можно загрузить с Lazarus-CCR:
  
http://sourceforge.net/projects/lazarus-ccr/files/CsvDocument/CsvDocument%200.3/csvdocument-0.3.zip/download
+
http://sourceforge.net/projects/lazarus-ccr/files/CsvDocument/CsvDocument%200.4/csvdocument-0.4.zip/download
  
 
Архив содержит саму библиотеку и демонстрационное приложение.
 
Архив содержит саму библиотеку и демонстрационное приложение.
 +
 +
Разрабатываемую версию можно получить из svn-репозитория Lazarus-CCR:
 +
 +
  svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/csvdocument csvdocument
  
 
=== Установка и использование ===
 
=== Установка и использование ===
  
 
Достаточно добавить модуль CsvDocument в секцию ''uses''. Если необходимо, можно установить путь к модулю в свойствах проекта.
 
Достаточно добавить модуль CsvDocument в секцию ''uses''. Если необходимо, можно установить путь к модулю в свойствах проекта.
 +
Другой вариант:
 +
 +
1. Откройте файл "csvdocument_package.lpk" из Lazarus IDE, используя меню: "Пакет -> Открыть файл пакета (.lpk) ...".
 +
 +
2. Скомпилируйте пакет.
 +
 +
3. Откройте ваш проект.
 +
 +
4. Добавьте пакет в качестве зависимости для вашего проекта с помощью Инспектора проекта.
  
 
=== Обратная связь ===
 
=== Обратная связь ===

Revision as of 06:45, 11 May 2011

English (en) русский (ru)

О библиотеке

Библиотека 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

Лицензия

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.

Статус

Beta

Загрузка

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

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

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

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

 svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/csvdocument csvdocument

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

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

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

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

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

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

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

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