todos README ============ Ilya V. Portnov todos — это простой TODO-менеджер. Сами записи TODO описываются в простом текстовом файле, а todos позволяет показывать из них только нужные, работая как специализированная утилита grep. При этом формат вывода по умолчанию совпадает с форматом входных файлов, поэтому вывод todos можно опять подавать на вход todos через конвейер. Если входные файлы не указаны в командной строке, читается файл TODO в текущей директории. Если вместо имени файла указано «-», читается стандартный ввод. todos поддерживает два формата входных файлов. В первом случае файл содержит только сами записи TODO и ничего больше. В «альтернативном» формате входные файлы могут содержать произвольный текст, но он игнорируется, а читаются только строки, начинающиеся с заданного префикса (по умолчанию TODO:), при этом формат строки после префикса тот же, что в первом случае. Альтернативный формат позволяет отбирать записи TODO из произвольных файлов, например исходных текстов программы. Формат записи TODO следующий: [spaces]status (dates) [TAGS] title (depends) description Здесь [spaces] — это необязательный отступ пробелами, status — статус записи (например URGENT или DONE, но может быть произвольным словом), dates — информация о датах (см. ниже), TAGS — список тегов через пробел в квадратных скобках, title — заголовок записи, depends — список зависимостей (заголовков других записей) в скобках через запятую, description — описание записи. Все поля кроме статуса и заголовка необязательны. Описание отделяется от заголовка не менее чем двумя пробелами. С помощью разных отступов можно создавать вложенные записи. Кроме того, зависимости интерпретируются также как вложенные записи; они позволяют создавать не только дерево записей, но и произвольный граф, в том числе и с циклами. В случае наличия циклов (когда задача A зависит от B, а B — от A) контроль за разумным выводом программы возлагается на пользователя (например, можно ограничить высоту выводимого дерева опцией -p). Информация о датах записывается в скобках, в виде не более чем трёх записей через точку с запятой, каждая запись имеет вид «тип_даты: дата». Тип даты может быть start, end, или deadline (предполагается, что так обозначаются соответственно дата начала выполнения задачи, планируемая дата окончания и дедлайн соответственно). Для дат поддерживается довольно много форматов; например, «18 Feb», или «02/18/2010», и мн. др. Тут могут указываться и относительные даты (вида «in 2 weeks», «2 days ago» или просто «tomorrow»), но это имеет мало смысла — относительные даты считаются от момента запуска программы. Поддерживаются следующие опции командной строки: -1, --only-first :: показывать только первую запись из всех, что должны быть показаны -c, --color :: раскрашивать вывод todos (заголовки записей — полужирным, некоторые статусы выделяются цветом) -A, --prefix= :: использовать альтернативный формат файлов, тут же указывается префикс -D, --describe :: можно указать формат для выводимого описания (см. ниже) -p, --prune :: ограничить максимальную высоту дерева (для каждой из отобранных записей будет показано не более чем N уровней вложенности) -m, --min-depth :: ограничить минимальную высоту дерева -t, --tag :: вывести только записи с заданным тегом и их вложенные записи -g, --grep :: искать по заголовкам записей -s, --status :: искать по статусам записей -a, --and :: логическое И; например, todos -s! -a -tBUG — искать записи со статусом «!» и тегом «BUG» -o, --or :: логическое ИЛИ; -n, --not :: логическое НЕ; -e, --exec :: вместо того, чтобы показывать записи, для каждой записи выполнить заданную команду; в строке для команды можно использовать символы подстановки, см. ниже -S, --start-date :: искать по дате начала -E, --end-date :: искать по планируемой дате завершения -d, --deadline :: искать по дедлайну -h, --help :: показать краткую справку по опциям командной строки Даты в командной строке могут быть во всех тех же форматах, что и во входных файлах. Тут как раз обычно более удобны относительные даты. Если указана дата в прошлом, записи ищутся по признаку «больше или равно», например, todos --deadline=yesterday будет искать записи с дедлайном вчера, сегодня или где угодно в будущем. Если указана дата в будущем, записи ищутся по признаку «меньше или равно»; например, todos --start-date="in 2 weeks" будет искать записи с датой начала через 2 недели или раньше (в т.ч. и в прошлом). Для опций --describe и --exec указываются строки формата с символами подстановки в стиле printf. Поддерживаются следующие символы подстановки: %n :: заменяется на заголовок записи %t :: список тегов записи %s :: статус записи %d :: описание записи %f :: имя файла, в котором встретилась запись %l :: номер строки в файле, где встретилась запись Например, todos -tBUG -e"vi %f +%l" для каждой записи с тегом BUG откроет vi на строчке с этой записью. todos может читать конфигурационные файлы: ~/.config/todos (глобальный) и .todos.conf в текущей директории (локальный). Конфигурационные файлы содержат ключи командной строки. «Эффективная командная строка» составляется как (ключи в глобальном конфиге) + (ключи в локальном конфиге) + ключи в командной строке. Если какого-то из конфигов нет, todos это проигнорирует.