{"id":13895509,"url":"https://github.com/ColumPaget/almanac","last_synced_at":"2025-07-17T11:31:18.672Z","repository":{"id":57914525,"uuid":"114502102","full_name":"ColumPaget/almanac","owner":"ColumPaget","description":"A command-line webcalendar display app for unix systems. Written in lua using 'libUseful-lua' ","archived":false,"fork":false,"pushed_at":"2024-07-25T15:33:45.000Z","size":341,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-07T18:34:37.536Z","etag":null,"topics":["cli","lua"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColumPaget.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-17T01:41:33.000Z","updated_at":"2024-07-25T15:33:33.000Z","dependencies_parsed_at":"2024-04-16T01:48:28.851Z","dependency_job_id":"01323a02-b08f-4b05-916a-1cdd8ee6ceeb","html_url":"https://github.com/ColumPaget/almanac","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColumPaget%2Falmanac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColumPaget%2Falmanac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColumPaget%2Falmanac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColumPaget%2Falmanac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColumPaget","download_url":"https://codeload.github.com/ColumPaget/almanac/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226255416,"owners_count":17595860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","lua"],"created_at":"2024-08-06T18:02:16.247Z","updated_at":"2024-11-25T00:31:42.531Z","avatar_url":"https://github.com/ColumPaget.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"## almanac - a calendar viewer written in lua for unix systems\n\nauthor: Colum Paget (colums.projects@gmail.com)  \nlicence: GPLv3  \n\nAlmanac is a calendar app that can store events in a local calendar, and display them as a simple list of events. It can download events from google calendars, meetup.com calendars, rss feeds with xCal extensions and iCal/ics feeds, and display these or add them to the local calendar. It can also insert events into a google calendar. It can output events in a number of formats, including csv, ical and 'sgical' which is the file format of Sanjay Ghemawat's 'ical' application.\n\n\n## Requirements\nTo use almanac you will need to have the following installed:\n\nlua              http://www.lua.org                          at least version 5.3  \nlibUseful        http://github.com/ColumPaget/libUseful      at least verson 3.6  \nlibUseful-lua    http://github.com/ColumPaget/libUseful-lua  at least version 1.2  \n\nyou will need swig (http://www.swig.org) installed to compile libUseful-lua\n\n\n## Build/install\n\nthe distribution comes as a load of .lua files that are compiled into a single 'almanac.lua' file using 'make'. A premade 'almanac.lua' is provided. You can copy this to anywhere in your path and run it with lua (`lua \u003cpath\u003e`, e.g `lua /usr/local/bin`), or else use linux's 'binfmt' system to invoke lua for lua scripts.\n\n'make install' copies almanac.lua to /usr/local/bin\n\n## Example calendars\n\nSome example calendars you might want to view are:\n\n## Google calendars. Note leading 'g:' prefix for use with almanac (unforunately many of these seem dead after covid lockdowns)\n```\ng:calendar@hackercons.org\ng:ukkchmv8h0pofbg4if8bekv5d4@group.calendar.google.com   - Royal Astronomical Society public lectures\ng:t60v6emjlovt3b6udm0bgie1l8@group.calendar.google.com   - Royal Astronomical Society meetings\ng:theuniversityofedinburgh@gmail.com                     - Events at edingburgh uni\ng:whatson@sheffield.ac.uk                                - Events at sheffield uni\ng:o4m8d0vra0ocig1etsuvbb1d6uckv519@import.calendar.google.com  - Bristol Uni philosophy department\ng:ledd3p7h7mpfulbn5hih6pohj8@group.calendar.google.com   - Sheffield Hackspace\n```\n\n\n## Meetup calendars. Note leading 'm:' prefix for use with almanac\n```\nm:fizzPOP-Birminghams-Makerspace   - my local hacker/maker space\n```\n\n## ICAL calendars online (these are becoming fewer)\n```\nhttps://calendar.google.com/calendar/ical/nextspaceflight.com_l328q9n2alm03mdukb05504c44%40group.calendar.google.com/public/basic.ics      - nextspaceflight.com upcoming launches\nhttp://events.ucl.ac.uk/calendar/events.ics                        - Events at University College London \nhttp://www.sussex.ac.uk/broadcast/feed/event/sussex-lectures.ics   - Sussex Uni public lectures\nhttps://www.dur.ac.uk/scripts/events/ical.php?category=51          - Durham Uni public lectures\nhttps://www.snb.ch/en/mmr/events/id/calendar_full_2018.en.ics      - Bank of Switzerland events 2018\n```\n\n\nYou can find a bunch of ical calendars here:\n\n```\nhttp://icalshare.com/\n```\n\n\n## RSS/xCal calendars\n\nNone of these seem to still be alive\n\n\nIf you find any other public calendars that people might be interested in, you can email them to me at 'colums.projects@gmail.com' and I'll add them to this list\n\n## Usage\n\n```\n almanac [options] [calendar]...\n```\n\nalmanac can pull calendar feeds from webcalendars using the google calendar api, meetup api, ical format, or xcal rss format\ngoogle and meetup calendars are identified in the following format:\ng:calendar@hackercons.org          - a google calendar\nm:fizzPOP-Birminghams-Makerspace   - a meetup calendar\n\nThe default calendar is stored on disk, and is referred to as 'a:default',  and if no calendar is supplied then it will be displayed by default\nical and rss webcalendars are identified by a url as normal.\nEvents can also be uploaded to google calendars that the user has permission for. If pushing events to a user's google calendar, or displaying events from it, this can be specified as 'g:primary'\n\n```\noptions:\n   -h \u003cn\u003e                         show events for the next 'n' hours. The 'n' argument is optional, if missing 1 day will be assumed\n   -hour \u003cn\u003e                      show events for the next 'n' hours. The 'n' argument is optional, if missing 1 day will be assumed\n   -d \u003cn\u003e                         show events for the next 'n' days. The 'n' argument is optional, if missing 1 day will be assumed\n   -day  \u003cn\u003e                      show events for the next 'n' days. The 'n' argument is optional, if missing 1 day will be assumed\n   -days \u003cn\u003e                      show events for the next 'n' days. The 'n' argument is optional, if missing 1 day will be assumed\n   -w \u003cn\u003e                         show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 week will be assumed\n   -week \u003cn\u003e                      show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 week will be assumed\n   -m \u003cn\u003e                         show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 month will be assumed\n   -month \u003cn\u003e                     show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 month will be assumed\n   -y \u003cn\u003e                         show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 year will be assumed\n   -year \u003cn\u003e                      show events for the next 'n' weeks. The 'n' argument is optional, if missing 1 year will be assumed\n   -at \u003cloc\u003e                      show events at location 'loc'\n   -where \u003cloc\u003e                   show events at location 'loc'\n   -location \u003cloc\u003e                show events at location 'loc'\n   -hide \u003cpattern\u003e                hide events whose title matches fnmatch/shell style pattern 'pattern'\n   -show \u003cpattern\u003e                show only events whose title matches fnmatch/shell style pattern 'pattern'\n   -detail                        print event description/details\n   -details                       print event description/details\n   -show-url                      print event with event connect url (for Zoom or Teams meetings) on a line below\n   -old                           show events that are in the past\n   -import \u003curl\u003e                  Import events from specified URL (usually an ical file) into calendar\n   -import-email \u003curl\u003e            Import events from ical attachments within an email file at the specified URL into calendar\n   -email \u003curl\u003e                   Import events from ical attachments within an email file at the specified URL into calendar\n   -mbox \u003curl\u003e                    Import events from an mbox file of emails. Has been seen to work with at least Thunderbird's mbox format.\n   -import-mbox \u003curl\u003e             Import events from an mbox file of emails. Has been seen to work with at least Thunderbird's mbox format.\n   -mbox \u003curl\u003e                    Import events from an mbox file of emails. Has been seen to work with at least Thunderbird's mbox format.\n   -persist                       don't exit, but print out events in a loop. This can be used to create an updating window that displays upcoming events.\n   -convert \u003curl\u003e                 Output events from specified URL (usually an ical file) in output format set with '-of'\n   -convert-email \u003curl\u003e           Output events from ical attachments within an email file at the specified URL in format set with '-of'\n   -lfmt \u003cformat string\u003e          line format for ansi output (see 'display formats' for details of title strings)\n   -xt \u003ctitle string\u003e             when -persist is used, also set the xterm title to be \u003ctitle string\u003e (see 'display formats' for details of title strings)\n   -xtitle \u003ctitle string\u003e         when -persist is used, also set the xterm title to be \u003ctitle string\u003e (see 'display formats' for details of title strings)\n   -xterm-title \u003ctitle string\u003e    when -persist is used, also set the xterm title to be \u003ctitle string\u003e (see 'display formats' for details of title strings)\n   -of \u003cfmt\u003e                      specify format to output. '\u003cfmt\u003e will be one of 'csv', 'ical', 'sgical', 'txt' or 'ansi'. Default is 'ansi'. See 'Output Formats' below for more details\n   -refresh \u003clen\u003e                 when in persist mode, update with this frequency, where 'len' is a number postfixed by 'm' 'h' 'd' or 'w' for 'minutes', 'hours', 'days' or 'weeks'. e.g. '2d' two days, '30m' thiry minutes. Default 2m.\n   -maxlen \u003clen\u003e                  When importing calendars set the max length of an event to \u003clen\u003e where len is a number postfixed by 'm' 'h' 'd' or 'w' for 'minutes', 'hours', 'days' or 'weeks'. e.g. '2d' two days, '30m' thiry minutes.\n   -u                             Terminal supports unicode up to code 0x8000\n   -unicode                       Terminal supports unicode up to code 0x8000\n   -u2                            Terminal supports unicode up to code 0x8000\n   -unicode2                      Terminal supports unicode up to code 0x10000\n   -?                             This help\n   -h                             This help\n   -help                          This help\n   --help                         This help\n\n```\n\n\n## ADD EVENTS\n\nThe following options all relate to inserting an event into an almanac or a google calendar. if calendar is specified then the default almanac calendar (a:default) is assumed. You can instead use the user's primary google calendar by specifiying 'g:primary'\n```\n   -add \u003ctitle\u003e           add an event with specified title using the destination calendars default privacy setting\n   -addpub \u003ctitle\u003e        add a public event with specified title\n   -addpriv \u003ctitle\u003e       add a private event with specified title\n   -start \u003cdatetime\u003e      start time of event (see 'time formats' below)\n   -end \u003cdatetime\u003e        end time of event (see 'time formats' below)\n   -at \u003clocation\u003e         location of event\n   -where \u003clocation\u003e      location of event\n   -location \u003clocation\u003e   location of event\n   -recur \u003cduration\u003e      event recurrs every '\u003cduration\u003e'. Duration has the format \u003cnumber\u003e\u003csuffix\u003e where suffix can be y=year,m=month,w=week,d=day,h=hour,m=minute. e.g. '-recur 2w' to recur every two weeks.\n   -import \u003cpath\u003e         import events from a .ical/.ics file and upload them to a calendar\n```\n\nexample: almanac.lua -add \"dental appointment\" -start \"2020/01/23\"\n\n##PERSIST MODE\n\nIf the '-persist' command-line flag is provided, then persistent/interactive mode is enabled. In this mode almanac prints out a list of events, then waits a 'refresh interval' and prints it out again with any updates that have occurred. This provides a persistent 'event list'. In this mode one can move forwards and backwards through the calendar using the left and right arrow keys, or else the ',' and '.' keys. The size of each 'page' depends on the interval requested with the '-w' or '-d' options. The 'space' key returns the calendar to 'now' and pressing the escape-key twice causes almanac.lua to exit.\n\ne.g. for a persistent eventlist with a page-size of 2 weeks:\n\n```\nalmanac.lua -persist -w 2\n```\n\n\n##TIME FORMATS\n\nalmanac accepts the following date/time formats:\n\nHH:MM                 -  4 digit time, date is 'today'\nHH:MM:SS              -  6 digit time, date is 'today'\nYYYYMMDD              -  8 digit date, e.g. 19890101\nYY?MM?DD              -  6 digit date with any separator character OTHER THAN ':' (so ? can be anything, e.g. 89/01/01)\nYYYY?MM?DD            -  8 digit date with any separator character (so ? can be anything, e.g. 1989:01:01)\nYYYYMMDDTHHMM         -  8 digit date with time e.g. 19890101T11:40:00\nYYYYMMDDTHHMMSS       -  8 digit date with time e.g. 19890101T11:40:00\nYYYYMMDDTHHMMSSZ      -  8 digit date with time e.g. 19890101T11:40:00Z\nYYYY?MM?DDTHH?MM?SS   -  8 digit date with time e.g. 1989/01/01T11:40:00\n\nCurrently the following *discouraged* formats are also supported. Almanac doesn't have locale support yet and these support UK/international date format\n\nDD?MM?YYYY            -  8 digit date with any separator character (so ? can be anything, e.g. 1989:01:01)\nDD?MM?YYYYTHH?MM?SS   -  8 digit date with time e.g. 1989/01/01T11:40:00\n\n\n## OUTPUT FORMATS\n\nthe '-of' option can specify one of the following output formats:\n```\ncsv     output comma-seperated-values suitable for reading into a spreadsheet.\ntxt     output plain text format.\nical    output ical/ics format.\nsgical  output file format sutable for Sanjay Ghemawat's unix ical application.\nansi    output text with ANSI color formatting\n```\n\n## DISPLAY FORMATS\n\nIn the default mode, ansi display mode, you can specify the line-by-line output format by using a combination of color identifiers and data identifiers.\ndata identifiers: these are strings that will be replaced by the specified value\n```\n$(title)           event title/summary\n$(date)            start date of displayed calendar in Y/m/d format\n$(time)            start time of displayed calendar in H:M:S format\n$(day)             numeric day of month\n$(month)           numeric month of year\n$(Year)            year in 4-digit format\n$(year)            year in 2-digit format\n$(monthname)       Full name of month ('Feburary')\n$(monthnick)       Short name of month ('Feb')\n$(dayname)         full name of day (Monday, Tuesday, Wednesday...)\n$(daynick)         short name of day (Mon, Tues, Wed...)\n$(dayid)           like dayname, except including 'today' and 'tomorrow'\n$(dayid_color)     like dayid, but today will be in ansi red, tomorrow in ansi yellow\n$(daynick_color)   like daynick, but today will be in ansi red, tomorrow in ansi yellow, although they will still have daynick names\n$(location)        event location\n$(duration)        event duration\n$(todayname)       name of today, regardless of what's being displayed on the calendar\n$(todaynick)       nick/short name of today, regardless of what's being displayed on the calendar\n$(nowtime)         time now, regardless of what's displayed on the calendar\n$(nowdate)         date now, regardless of what's displayed on the calendar\n$(nowyear)         year now, regardless of what's displayed on the calendar\n$(nowmonth)        month number now, regardless of what's displayed on the calendar\n$(nowday)          day number now, regardless of what's displayed on the calendar\n$(nowhour)         hour now, regardless of what's displayed on the calendar\n$(nowmin)          minutes now, regardless of what's displayed on the calendar\n$(nowsec)          seconds now, regardless of what's displayed on the calendar\n``\n\ncolor identifiers: format strings that specifier colors\n```\n~0      reset colors\n~r      red\n~g      green\n~b      blue\n~y      yellow\n~m      magenta\n~c      cyan\n~w      white\n~n      noir (black)\n~e      bold (emphasis)\n```\n\ndefault display format is:  `~c$(dayid_color)~0 $(date) $(time_color) $(duration) ~e~m$(title)~0 $(location)`\n\n## EXAMPLES\n\ndisplay default calendar\n```\n\talmanac.lua a:default\n```\n\ndisplay user's primary google calendar\n```\n\talmanac.lua g:primary\n```\n\ndisplay web calendar\n```\n\talmanac.lua https://launchlibrary.net/1.3/calendar/next/100\n```\n\noutput web calendar in format suitable for Sanjay Ghemawat's 'ical' program, and redirect to a file that ical can import\n```\n\talmanac.lua -of sgical https://launchlibrary.net/1.3/calendar/next/100 \u003e launches.calendar\n```\n\noutput web calendar in CSV format suitable spreadsheet import\n```\n\talmanac.lua -of csv https://launchlibrary.net/1.3/calendar/next/100 \u003e launches.csv\n```\n\nadd event to almanac calendar\n```\n\talmanac.lua -add \"dental appointment\" -start \"2020/01/23\"\n\talmanac.lua a:default -add \"dental appointment\" -start \"2020/01/23\"\n```\n\nadd event to google calendar\n```\n\talmanac.lua g:primary -add \"dental appointment\" -start \"2020/01/23\"\n\talmanac.lua g:me@mydomain.org -add \"next meeting\" -start \"2020/01/23\"\n```\n\nimport an ical url into local calendar\n```\n\talmanac.lua a:default -import https://launchlibrary.net/1.3/calendar/next/100\n```\n\nimport all ical attachments in an email file into local calendar\n```\n\talmanac.lua a:default -import-email mailfile.mail\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FColumPaget%2Falmanac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FColumPaget%2Falmanac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FColumPaget%2Falmanac/lists"}