Справочник: инструменты¶
Сервер отдаёт два инструмента. До клиента их имена доходят с префиксом из имени, которое вы дали серверу: с именем worklog это worklog_append и worklog_check.
append¶
Записывает одну законченную работу.
| Аргумент | Тип | По умолчанию | Значение |
|---|---|---|---|
description |
string | обязателен | Что сделано, одной фразой |
dry_run |
boolean | false |
Вернуть строку, которая была бы записана, не записывая её |
Результат — объект из четырёх полей:
| Поле | Тип | Значение |
|---|---|---|
status |
string | Что произошло, см. ниже |
file |
string | null | Имя лог-файла, без каталога |
line |
string | null | Записанная строка или та, что была бы записана |
message |
string | Одна фраза с описанием исхода |
Статусы¶
status |
Записано? | Значение |
|---|---|---|
written |
да | Пункт дописан в существующий чек-лист |
created |
да | Чек-листа в файле не было, он заведён этим же пунктом |
duplicate |
нет | Такой пункт в чек-листе уже был |
dry_run |
нет | Был задан dry_run; в line — что попало бы в файл |
empty |
нет | После нормализации описание оказалось пустым |
no_dir |
нет | Каталог не задан или не существует |
no_file |
нет | В каталоге нет подходящего файла |
О created стоит сказать пользователю: в его файле появился список, которого там не было (подробности).
Последние два — отсутствующие предпосылки. О них нужно сообщить, а не пытаться их создать (почему).
Файл, не являющийся корректным UTF-8, и неудавшаяся запись возвращаются ошибкой инструмента, а не статусом; в сообщении будут имя файла и причина.
check¶
Сообщает, находится ли прямо сейчас лог-файл с чек-листом. Аргументов не принимает.
| Поле | Тип | Значение |
|---|---|---|
status |
string | ok, no_dir, no_file или no_checklist |
file |
string | null | Имя лог-файла, без каталога |
items |
integer | null | Сколько пунктов уже есть в чек-листе |
message |
string | Одна фраза с описанием исхода |
Он существует, чтобы отличить неверно настроенный сервер от лога, который сегодня ещё не начат. Читать лог им нельзя: пункты считаются, но не возвращаются.
В отличие от append, он никогда не заводит чек-лист — файл без него возвращается статусом no_checklist и остаётся нетронутым.
Чего не бывает в ответе¶
Ни один результат обоих инструментов не содержит пути в файловой системе, имени каталога и содержимого файла — кроме единственной только что записанной строки. Это относится и к сообщениям об ошибках.