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 — описание записи. Все поля кроме статуса и заголовка необязательны. В случае, если указана опция «-w», поле статуса не читается. Описание отделяется от заголовка не менее чем двумя пробелами. С помощью разных отступов можно создавать вложенные записи. Кроме того, зависимости интерпретируются также как вложенные записи; они позволяют создавать не только дерево записей, но и произвольный граф, в том числе и с циклами. В случае наличия циклов (когда задача 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 (заголовки записей — полужирным, некоторые статусы выделяются цветом) -H, --highlight :: подсвечивать подходящие записи, вместо того чтобы фильтровать их -I, --show-ids :: показывать идентификаторы записей -A, --prefix= :: использовать альтернативный формат файлов, тут же указывается префикс --dot :: вывести записи в виде графа для DOT (graphviz) -D, --format :: можно указать формат вывода записей (см. ниже) -k, --indent-string :: использовать указанную строку для создания отступов, вместо двух пробелов -w, --no-status :: не читать поле статуса из файлов --set-status=STRING :: установить статус всех TODO равным STRING --set-root-status=STRING :: установить статусы корневых TODO равным STRING -F, --by-file :: группировать записи по исходному файлу -T, --by-tag :: группировать записи по тегам -Z, --by-status :: группировать записи по статусам -p, --prune :: ограничить максимальную высоту дерева (для каждой из отобранных записей будет показано не более чем N уровней вложенности) -m, --min-depth :: ограничить минимальную высоту дерева -t, --tag :: вывести только записи с заданным тегом и их вложенные записи -g, --grep :: искать по заголовкам записей -G, --description :: искать по описаниям записей -s, --status :: искать по статусам записей -i, --id :: искать по идентификаторам записей -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 недели или раньше (в т.ч. и в прошлом). С указанной опцией «-H» записи не фильтруются совсем. Вместо этого те записи, которые подходят под ваш запрос, будут подсвечены цветом (только с включённой опцией «-c»). Если указана опция «-I», перед каждой записью будет напечатан её идентификатор. Идентификатор записи — это просто хэш от заголовка, описания, статуса, тегов и описания; так что только одинаковые записи будут иметь одинаковые идентификаторы. Можно попросить вывести только запись с данным идентификатором при помощи опции «-i». С помощью опции «-k» можно указать другую строку для формирования отступов при выводе записей в консоль. По умолчанию используются два пробела. Попробуйте, например, `todos -k"| "`. Опция «-k» без аргумента отключает формирование отступов совсем. Для опций --format и --exec указываются строки формата с символами подстановки в стиле printf. Поддерживаются следующие символы подстановки: %n :: заменяется на заголовок записи %t :: список тегов записи %s :: статус записи %p :: префикс перед записью %d :: описание записи %f :: имя файла, в котором встретилась запись %l :: номер строки в файле, где встретилась запись %D :: даты, связанные с записью Кроме того, поддерживается экранирование с помощью бэкслэша. Поддерживаются следующие последовательности: '\t \n \v \b`. Например, todos -tBUG -e"vi %f +%l" для каждой записи с тегом BUG откроет vi на строчке с этой записью. С опцией «--dot» todos выведет на стандартный выход описание графа для DOT (graphviz) вместо обычного вывода. Можно попробовать, например, так: todos --dot | dot -Tpng -o todos.png и см. получившийся файл todos.png. Записи со статусом «GROUP» становятся кластерами. Точнее говоря, если какая-то запись имеет статус «GROUP», она будет отображаться как кластер, а все её дочерние записи будут находиться внутри этого кластера. При этом есть одно ограничение, накладываемое DOT: DOT не умеет правильно рисовать графы, в которых один узел находится сразу в нескольких кластерах; в таких случаях узел будет нарисован только в одном кластере. todos может читать конфигурационные файлы: `~/.config/todos/todos.conf` (глобальный) и `.todos.conf` в текущей директории (локальный). Кроме того, todos ищет файлы с именем `.todos.conf` во всех родительских директориях. Например, если текущая директория — `/home/user/work/projects`, будут проверены следующие файлы: * `/home/user/work/projects/.todos.conf` * `/home/user/work/.todos.conf` * `/home/user/.todos.conf` * `/home/.todos.conf` * `/.todos.conf` Если один из этих файлов существует, todos проверяет, не начинается ли он со слова «%» (один знак процента). Если начинается, то будет прочитан «родительский» конфигурационный файл (из ближайшей родительской директории), и ключи из него будут подставлены на место этого знака процента. В противном случае (если конфигурационный файл не начинается с «%»), конфигурационные файлы из родительских директорий игнорируются. Конфигурационные файлы содержат ключи командной строки. «Эффективная командная строка» составляется как (ключи в глобальном конфиге) + (ключи в локальном конфиге) + ключи в командной строке. Если какого-то из конфигов нет, todos это проигнорирует. Например, если в файле `/home/user/work/projects/.todos.conf` написано `% --dot`, а в файле `/home/user/work/.todos.conf` написано `-A -F`, то «эффективная командная строка» будет иметь вид `-A -F --dot`. Конфигурационные файлы могут указываться в командной строке. Параметр командной строки `@path/to/file.conf` указывает, что нужно прочитать файл `path/to/file.conf` и добавить ключи из него перед остальными ключами командной строки (но после ключей из глобальных и локальных конфигурационных файлов). Параметр вида `@@path/to/file.conf` работает аналогично, но запрещает чтение глобальных и локальных конфигурационных файлов. Просто заставить todos не читать (глобальные и локальные) конфигурационные файлы можно параметром `@@`. Кроме того, todos можно настраивать под себя «в стиле xmonad». Вы пишете файл `~/.config/todos/todos.hs` и запускаете todos. todos компилирует и запускает тот файл. Простейший возможный пример этого `todos.hs` — это файл `todos.hs` в этой директории. Вот чуть более сложный пример: ................................................................. import System.Console.ANSI import Todos main :: IO () main = todos $ defaultConfig { itemConsoleColor = myItemColor } myItemColor item = if itemStatus item == ":" then Just (Dull, Blue) else Nothing ................................................................. Таким образом, записи со статусом «:» будут напечатаны синим цветом.