Отчёт о ходе выполнения операции

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

Вот рабочий пример, который ничего полезного не делает:

(let ((progress-reporter
       (make-progress-reporter "Collecting mana for Emacs..."
                               0  500)))
  (dotimes (k 500)
    (sit-for 0.01)
    (progress-reporter-update progress-reporter k))
  (progress-reporter-done progress-reporter))

Функция: make-progress-reporter message &optional min-value max-value current-value min-change min-time

Эта функция создаёт и возвращает объект отчёта о ходе выполнения, который вы будете использовать в качестве аргумента для других функций, перечисленных ниже. Идея заключается в том, чтобы предварительно вычислить как можно больше данных, чтобы отчёт о ходе выполнения был очень быстрым.

Когда этот отчёт о ходе выполнения используется в дальнейшем, он отображает message в области эха, за которым следует процент выполнения. message обрабатывается как простая строка. Если вам нужно, чтобы он зависел от имени файла, например, используйте format-message перед вызовом этой функции.

Аргументы min-value и max-value должны быть числами, представляющими начальное и конечное состояния операции. Например, операция сканирования буфера должна установить эти значения в результаты point-min и point-max соответственно. max-value должно быть больше, чем min-value.

В качестве альтернативы, вы можете установить min-value и max-value в nil. В этом случае отчёт о ходе выполнения не отображает проценты выполнения; вместо этого он отображает «спиннер», который поворачивает вырез каждый раз, когда вы обновляете отчёт о ходе выполнения.

Если min-value и max-value являются числами, вы можете присвоить аргументу current-value числовое значение, определяющее начальное выполнение; если он опущен, по умолчанию он равен min-value.

Остальные аргументы контролируют скорость обновлений области эха. Отчёт о ходе выполнения будет ждать по крайней мере min-change дополнительных процентов завершения операции перед отображением следующего сообщения; значение по умолчанию составляет один процент. min-time задаёт минимальное время в секундах, которое должно пройти между последовательными выводами; значение по умолчанию составляет 0,2 секунды. (На некоторых операционных системах отчёт о ходе выполнения может обрабатывать доли секунды с различной точностью).

Эта функция вызывает progress-reporter-update, поэтому первое сообщение отображается немедленно.

Функция: progress-reporter-update reporter &optional value suffix

Эта функция выполняет основную работу по отображению хода вашей операции. Она отображает сообщение reporter, за которым следует процент выполнения, определяемый value. Если процент равен нулю или достаточно близок к нему в соответствии с аргументами min-change и min-time, то он опускается из вывода.

reporter должен быть результатом вызова make-progress-reporter. value определяет текущее состояние вашей операции и должен находиться в диапазоне от min-value до max-value (включительно), переданных в make-progress-reporter. Например, если вы сканируете буфер, то value должен быть результатом вызова point.

Необязательный аргумент suffix — это строка, отображаемая после основного сообщения reporter и текста процента выполнения. Если reporter — это не числовой отчёт, то value должен быть nil, или строкой, используемой вместо suffix.

Эта функция учитывает min-change и min-time, переданные в make-progress-reporter, и поэтому не выводит новые сообщения при каждом вызове. Таким образом, она очень быстрая, и обычно вам не следует пытаться уменьшить количество вызовов: издержки, скорее всего, перевесят ваши усилия.

Функция: progress-reporter-force-update reporter &optional value new-message suffix

Эта функция аналогична progress-reporter-update за исключением того, что она безусловно выводит сообщение в области эха.

reporter, value и suffix имеют такое же значение, как и для progress-reporter-update. Необязательный new-message позволяет вам изменить сообщение reporter. Поскольку эта функция всегда обновляет область эха, такое изменение будет немедленно представлено пользователю.

Функция: progress-reporter-done reporter

Эта функция должна быть вызвана по завершении операции. Она выводит сообщение reporter, за которым следует слово «завершено» в области эха.

Вы всегда должны вызывать эту функцию и не надеяться на progress-reporter-update для вывода «100%». Во-первых, она может его никогда не вывести, есть много веских причин для этого. Во-вторых, «завершено» более явное.

Макрос: dotimes-with-progress-reporter (var count [result]) reporter-or-message body…

Это удобный макрос, который работает так же, как dotimes , но также сообщает о ходе цикла с помощью описанных выше функций. Он позволяет вам сэкономить на наборе текста.

Аргумент reporter-or-message может быть либо строкой, либо объектом отчёта о ходе выполнения.

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

(dotimes-with-progress-reporter
    (k 500)
    "Collecting some mana for Emacs..."
  (sit-for 0.01))

Использование объекта отчёта в качестве аргумента reporter-or-message полезно, если вы хотите указать необязательные аргументы в make-progress-reporter. Например, вы можете переписать предыдущий пример следующим образом:

(dotimes-with-progress-reporter
    (k 500)
    (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5)
  (sit-for 0.01))

Макрос: dolist-with-progress-reporter (var count [result]) reporter-or-message body…

Это ещё один удобный макрос, который работает так же, как dolist , но также сообщает о ходе цикла с помощью описанных выше функций. Как и в dotimes-with-progress-reporter, reporter-or-message может быть отчётом о ходе выполнения или строкой. Вы можете переписать предыдущий пример с помощью этого макроса следующим образом:

(dolist-with-progress-reporter
    (k (number-sequence 0 500))
    "Collecting some mana for Emacs..."
  (sit-for 0.01))