From bff5f8c2d11e747644779ac09c728dc7dad0cb40 Mon Sep 17 00:00:00 2001 From: katherine Date: Sat, 21 Dec 2019 21:36:28 -0700 Subject: add readme --- Readme.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 Readme.md (limited to 'Readme.md') diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..0685c1f --- /dev/null +++ b/Readme.md @@ -0,0 +1,172 @@ +every +===== + +*every* is a personal calendar tool, heavily inspired by the program +[when](http://www.lightandmatter.com/when/when.html). it reads from a file +containing a list of one-time or recurrent events, like this: + +``` +.warn 3d +.stay 2d + +on 2019-12-20 20:00, friend's party (bring gifts) + + +# short-term recurrent + +.warn 6H +.stay 6H +.urgent true + +every 10d from 2019-11-07 08:00 to 2020-01-27, prescribed medication + +.urgent false + + +# holidays + +.warn 10d +.stay 1d + +every 1y from _-12-24, クリスマスイブ！ + + + +# birthdays + +.warn 5d +.stay 3d + +every 1y from 1989-09-05, person a +every 1y from 1992-12-18, person b +``` + +and prints out which of those events are upcoming (within their `.warn` period) +or recent (within their `.stay` period): + +``` +Sat 2019 Dec 21 20:00 + + +[ URGENT ] + +Today 18:00 prescribed medication + + +[ normal ] + +Yesterday 20:00 friend's party (bring gifts) +2019 Dec 24 クリスマスイブ！ +``` + +i wrote this program because when, useful as it is, can't handle recurrent +events in the way i'd hoped it would, and in the process also added a few other +options that seemed useful, like an output mode for use in scripts. + + + +usage +----- + +``` +$ every --help +Usage: ./dbg_every [-c CALENDAR_FILE] [-e TEXT_EDITOR] [COMMAND] + + every is a simple console-based event calendar + + -h --help print this help message and exit + -v --version print the version of every in use and exit + -c --calendar=FILE path to calendar file + -e --editor=CMD text editor for editing calendars + --line-delim=CHAR line delimiter for scripting output + --col-delim=CHAR column delimiter for scripting output + +Commands + c (default) print upcoming events in interactive console mode + s print upcoming events in a format appropriate for scripting + e open calendar with text editor +``` + +every has three basic commands: + +### edit + +`every e` is a shortcut for opening the default +calendar using `$EDITOR` (or the specified calendar using the specified +command). the default calendar is `every/cal.every` under `$XDG_CONFIG_HOME` +(which falls back to `$HOME/.config/` when not specified) + +if you use vim, a syntax file for the `.every` file format is available here: +https://git.airen-no-jikken.icu/ageha/every.vim + +### console + +`every c` prints out the upcoming events in a human-readable format, suitable +for interactive use. this is the default command, so just `every` is +equivalent. + +### script + +`every s` prints the upcoming events in an easily-parseable format, for use in +scripting. each line (by-default terminated in `\n`) represents one upcoming +event, with fields (by default) delimited with `\t`. + +the fields are: + +| year | month | day | hour | minute | second | urgent | local | message | + + + +calendar format +--------------- + +the calendar's grammar looks something like this: + +``` +CAL := CMD | ENTRY + + CMD := .local BOOL | .urgent BOOL | .warn INTERVAL | .stay INTERVAL +BOOL := yes | true | on | no | false | off + +ENTRY := on DATE + | on DATE , MESSAGE + | every INTERVAL from DATE + | every INTERVAL from DATE , MESSAGE + | every INTERVAL from DATE to DATE + | every INTERVAL from DATE to DATE , MESSAGE + +``` + +a `DATE` represents a single point in time in the form `y-m-d H:M:S`, where +trailing elements can be left off (so `2020-01-09 08:30` or even just `2020` +are valid) and any element can be replaced with an underscore to substitute it +with a default value (`_-12-09` == `2000-12-09`. `_-_-_ _:_:_` == `2000-01-01 +00:00:00`) + +an `INTERVAL` represents a duration of time, and is made of one to six numbers, +in any order, representing a number of years, months, days, hours, minutes and +seconds. each element uses a single char subscript to indicate its type (`1y 3d +2m` is one year, two months, three days. `1H3M2S` is one hour, three minutes, +two seconds). elements may not repeat (so `1y5H2d3y` is invalid) + +there are two types of calendar entries: `on` entries, for one-time events +occurring on a given `DATE`, and `every` entries, for events that recur every +`INTERVAL` amount of time. + +time intervals are calculated such that only the elements listed change. an +`every 1y from _-03-12` event will *always* occur on march 12th. this means +that the intervals `1y` and `365d` are not equivalent, because some years +contain leap days, and it also means that `every 1y from 2008-02-29` will occur +only during leap years + +a `MESSAGE` is an optional string describing the event that will be displayed +when printing. if present, it must begin with a `,` and lasts until the end of +the line + + + +note +---- + +this program requires a POSIX environment. it also makes use of the `timegm` +function, which is a non-standard extension but commonly implemented. -- cgit v1.2.3