csv

ИМЯ

csv — процедуры для работы с данными CSV.

Содержание

• Содержание

• Краткое описание

• Описание

• КОМАНДЫ

• ФОРМАТ

• ПРИМЕР

• Ошибки, идеи, обратная связь

• См. также

• Категория

• Авторские права

КРАТКОЕ ОПИСАНИЕ

package require Tcl 8.5 9
package require csv ?0.8.1?

::csv::iscomplete data
::csv::join values ?sepChar? ?delChar? ?delMode?
::csv::joinlist values ?sepChar? ?delChar? ?delMode?
::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?
::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
::csv::read2queue ?-alternate? chan q {sepChar ,}
::csv::report cmd matrix ?chan?
::csv::split ?-alternate? line ?sepChar? ?delChar?
::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
::csv::split2queue ?-alternate? q line {sepChar ,}
::csv::writematrix m chan ?sepChar? ?delChar?
::csv::writequeue q chan ?sepChar? ?delChar?

ОПИСАНИЕ

Пакет csv предоставляет команды для работы с информацией в ФОРМАТЕ CSV (CSV = значения, разделённые запятыми).

КОМАНДЫ

Доступны следующие команды:

• ::csv::iscomplete data

  Предикат, проверяющий, является ли аргумент data полной записью CSV. Результат — логический флаг, указывающий, являются ли данные полными. Результат равен true, если данные полные.

• ::csv::join values ?sepChar? ?delChar? ?delMode?

  Принимает список значений и возвращает строку в формате CSV, содержащую эти значения. Вызывающий код может задать символ-разделитель, но это необязательно. По умолчанию используется ",". Вызывающий код может задать символ кавычек (то есть ограничитель), но это необязательно. По умолчанию используется '"'. По умолчанию режим заключения в кавычки delMode равен "auto": значения окружаются символом delChar только при необходимости. Однако если задать значение "always", значения всегда будут окружаться символом delChar.

• ::csv::joinlist values ?sepChar? ?delChar? ?delMode?

  Принимает список списков значений и возвращает строку в формате CSV, содержащую эти значения. Вызывающий код может задать символ-разделитель, но это необязательно. По умолчанию используется ",". Вызывающий код может задать символ кавычек, но это необязательно. По умолчанию используется '"'. По умолчанию режим заключения в кавычки delMode равен "auto": значения окружаются символом delChar только при необходимости. Однако если задать значение "always", значения всегда будут окружаться символом delChar. Каждый элемент внешнего списка считается записью; в результирующей строке записи разделяются символами новой строки. Элементы каждой записи форматируются обычным образом (с помощью ::csv::join).

• ::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?

  Принимает объект matrix, соответствующий API, определённому для пакета struct::matrix, и возвращает строку в формате CSV, содержащую эти значения. Вызывающий код может задать символ-разделитель, но это необязательно. По умолчанию используется ",". Вызывающий код может задать символ кавычек, но это необязательно. По умолчанию используется '"'. По умолчанию режим заключения в кавычки delMode равен "auto": значения окружаются символом delChar только при необходимости. Однако если задать значение "always", значения всегда будут окружаться символом delChar. Каждая строка матрицы считается записью; в результирующей строке записи разделяются символами новой строки. Элементы каждой записи форматируются обычным образом (с помощью ::csv::join).

• ::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}

  Обёртка над ::csv::split2matrix (см. ниже), которая считывает строки в формате CSV из указанного канала (до EOF) и добавляет их в заданную матрицу. Описание аргумента expand см. в разделе о ::csv::split2matrix.

• ::csv::read2queue ?-alternate? chan q {sepChar ,}

  Обёртка над ::csv::split2queue (см. ниже), которая считывает строки в формате CSV из указанного канала (до EOF) и добавляет их в заданную очередь.

• ::csv::report cmd matrix ?chan?

  Команда формирования отчёта, которую могут использовать методы матрицы format 2string и format 2chan. Во втором случае эта команда делегирует работу ::csv::writematrix. Предполагается, что cmd имеет значение printmatrix или printmatrix2channel. Для второго варианта необходимо указать аргумент канала chan, а для первого его указывать нельзя.

• ::csv::split ?-alternate? line ?sepChar? ?delChar?

  Преобразует строку line в формате CSV в список содержащихся в ней значений. Вызывающий код может задать символ-разделитель значений через sepChar, но это необязательно. По умолчанию используется ",". Вызывающий код может задать символ кавычек, но это необязательно. По умолчанию используется '"'.

  Если указан параметр -alternate, для разбора входных данных используется немного другой синтаксис. Этот синтаксис описан ниже, в разделе ФОРМАТ.

• ::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}

  Работает так же, как ::csv::split, но добавляет полученный список в качестве новой строки матрицы m, используя метод add row. Режим расширения, заданный через expand, определяет, как команда обрабатывает матрицу, в которой столбцов меньше, чем значений в line. Допустимы следующие режимы:

  • none

    Это режим по умолчанию. В этом режиме вызывающий код должен обеспечить в матрице достаточное количество столбцов для размещения всей строки. Если столбцов недостаточно, список значений без предупреждения усекается в конце.

  • empty

    В этом режиме команда расширяет пустую матрицу, чтобы она содержала все столбцы указанной строки, но не расширяет её дальше. В результате первая строка последовательности определяет количество столбцов матрицы, а все последующие строки усекаются до этого размера, как если бы был задан режим none.

  • auto

    В этом режиме команда при необходимости расширяет матрицу, чтобы она содержала все столбцы из line. В результате после добавления последовательности строк матрица будет содержать достаточно столбцов для самой длинной из встретившихся строк.

• ::csv::split2queue ?-alternate? q line {sepChar ,}

  Работает так же, как ::csv::split, но добавляет полученный список в очередь q как один элемент, используя метод put.

• ::csv::writematrix m chan ?sepChar? ?delChar?

  Обёртка над ::csv::join, которая получает все строки матрицы m и записывает их в формате CSV в канал chan.

• ::csv::writequeue q chan ?sepChar? ?delChar?

  Обёртка над ::csv::join, которая получает все элементы очереди q (предполагается, что это списки) и записывает их в формате CSV в канал chan.

ФОРМАТ

Формат обычных файлов CSV определяется следующим образом:

1. Каждая запись CSV-файла (значения, разделённые запятыми, например, экспортированные из Excel) представляет собой набор значений ASCII, разделённых символом ",". В других языках вместо него может использоваться ";", но в данном случае это неважно, поскольку приведённые здесь функции позволяют задавать любой символ-разделитель.

2. Значение необходимо заключать в "", только если оно содержит символ-разделитель ",". Если значение не содержит символ-разделитель, его можно заключать в кавычки, но это необязательно.

3. Если значение содержит символ ", этот символ представляется как "".

4. Выходная строка "" представляет значение ". Другими словами, предполагается, что она была создана по правилу 3 и только по нему, то есть значение не было заключено в кавычки.

В альтернативном определении формата, используемом главным образом продуктами MS, выходная строка "" представляет пустую строку. Другими словами, предполагается, что выходная строка была получена из пустой строки путём заключения её в кавычки (то есть по правилу 2), а не по правилу 3. Это единственное различие между обычным и альтернативным форматами.

Альтернативный формат включается указанием параметра -alternate в различных командах разбиения.

ПРИМЕР

При использовании обычного формата запись

123,"123,521.2","Mary says ""Hello, I am Mary""",""

разбирается на элементы

a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) "

При использовании альтернативного формата результат будет таким:

a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) (the empty string)

Как видно, отличается только элемент (d): теперь это пустая строка, а не символ ".

Ошибки, идеи, обратная связь

В этом документе и описываемом в нём пакете, несомненно, есть ошибки и другие проблемы. Пожалуйста, сообщайте о них в категории csv в системе отслеживания ошибок Tcllib. Также сообщайте о любых идеях по улучшению пакета и/или документации.

Предлагая изменения кода, пожалуйста, предоставляйте унифицированные различия, то есть вывод команды diff -u.

Также обратите внимание: предпочтительно прикладывать вложения, а не вставлять патчи непосредственно в текст. Чтобы добавить вложение, сразу после создания заявки откройте форму Редактировать, а затем нажмите самую левую кнопку на дополнительной панели навигации.

СМ. ТАКЖЕ

matrix, queue

КАТЕГОРИЯ

Обработка текста

АВТОРСКИЕ ПРАВА

Авторские права © 2002-2015 Andreas Kupries