{"id":20200504,"url":"https://github.com/loteoo/icsp","last_synced_at":"2025-03-03T08:43:16.193Z","repository":{"id":147778524,"uuid":"618569243","full_name":"loteoo/icsp","owner":"loteoo","description":"Command-line iCalendar (.ics) to TSV / CSV utility. Written in Bash + AWK","archived":false,"fork":false,"pushed_at":"2024-07-04T13:13:03.000Z","size":22,"stargazers_count":102,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-24T06:53:51.147Z","etag":null,"topics":["awk","cli","command-line","csv","icalendar","icalendar-parsing","icalendar-rfc","ics","parser"],"latest_commit_sha":null,"homepage":"","language":"Awk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loteoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-03-24T18:58:21.000Z","updated_at":"2025-02-14T18:06:02.000Z","dependencies_parsed_at":"2024-01-07T21:08:08.864Z","dependency_job_id":"b0634e35-570b-4e25-8924-b116ed1c8773","html_url":"https://github.com/loteoo/icsp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loteoo%2Ficsp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loteoo%2Ficsp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loteoo%2Ficsp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loteoo%2Ficsp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loteoo","download_url":"https://codeload.github.com/loteoo/icsp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241637184,"owners_count":19994926,"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":["awk","cli","command-line","csv","icalendar","icalendar-parsing","icalendar-rfc","ics","parser"],"created_at":"2024-11-14T04:44:09.378Z","updated_at":"2025-03-03T08:43:16.165Z","avatar_url":"https://github.com/loteoo.png","language":"Awk","funding_links":[],"categories":["\u003ca name=\"organizers\"\u003e\u003c/a\u003eOrganizers and calendars"],"sub_categories":[],"readme":"\u003ca href=\"https://millisecond.studio/\"\u003e\n  \u003cimg src=\"https://cdn.thumbsmith.com/v1/u/loteoo/millisecond-github-banner.png?title=icsp+-+iCalendar+(.ics)+parser\u0026description=Command-line+iCalendar+(.ics)+to+TSV+%2F+CSV+utility.+Written+in+Bash+%2B+AWK\" alt=\"icsp banner\" /\u003e\n\u003c/a\u003e\n\n---\n\nSmall, fast and simple command-line tool to convert calendar exports (.ics files) into TSV/CSV files for easy analysis and usage in broader use-cases\n\nCombine this with CSV tools like [xsv](https://github.com/BurntSushi/xsv), [q](https://github.com/harelba/q), [csvkit](https://github.com/wireservice/csvkit) or [visidata](https://github.com/saulpw/visidata) for calendar data superpowers.\n\nWritten in pure bash and AWK. Compatible with most unix systems (ubuntu, macOS or windows with WSL).\n\n## Installation\n\nTo install icsp, you can use the install script:\n\n```sh\nbash \u003c(curl -fsSL \"https://raw.githubusercontent.com/loteoo/icsp/main/install\")\n```\n\n\u003cdetails\u003e\u003csummary\u003eOr, do a manual installation (click to expand):\u003c/summary\u003e\n\n1. Download the repo (via git clone or .zip download) and keep it somewhere\n2. Create a symlink from an executable BIN directory (such as /usr/local/bin, ~/.local/bin or ~/bin) to the `icsp` file in the directory that you downloaded.\n\nExample:\n\n```sh\n#         This bin directory should be in your executable $PATH\n#                                     /\nln -s ~/my-repos/icsp/icsp ~/.local/bin/icsp\n#                       \\\n#     This should be the actual icsp script file\n```\n\n\u003c/details\u003e\n\n## Usage\n\nRun `icsp -h` for usage.\n\n```\nicsp - iCalendar (.ics) parser. v1.0.0\n\nConvert iCalendar files to (and from) TSV files.\n\nUsage:\n  icsp [-c columns] [-d delimiter] [-x component] [-nrh] [...files]\n\nOptions:\n  -c \u003cstring\u003e   Comma seperated list of fields to parse. Order is preserved, case insensitive.\n  -d \u003cstring\u003e   Delimiter character to use for seperating values. Default: '\\t' (TAB character)\n  -x \u003cstring\u003e   ICS component to parse. Default: VEVENT\n  -n            No date conversion (faster processing, no DURATION column, no ISO format)\n  -r            Reverse conversion (Build ICS file from TSV)\n  -h            Show this help text.\n```\n\nBasic examples:\n\n```sh\n# Simple usage\nicsp calendar.ics \u003e calendar.tsv\n\n# Custom delimiter\nicsp -d ',' calendar.ics \u003e calendar.csv\n\n# Display specific fields\nicsp -c 'dtstart,summary,duration' calendar.ics \u003e calendar.tsv\n\n# Download calendar from the internet as TSV\ncurl https://foobar/path/to/calendar.ics | icsp \u003e calendar.tsv\n\n# Convert TSV file to iCalendar file\nicsp -r calendar.tsv \u003e calendar.ics\n```\n\n#### Usage notes:\n\nFor the `-c` option, if you don't specify it, icsp will return all fields found in the .ics file, sorted by how often they are populated. This is useful to quickly check what's in a file, but it is also usually pretty messy, so specifying the wanted columns and their order is probably recommended.\n\nThere is also a special `duration` column you can specify via `-c` that will be computed by icsp (unless already supplied by the iCalendar file). This is often useful because calendar providers usually don't provide this value directly even if it's really useful for viewing the calendar data.\n\nThe default delimiter for the `-d` option is a TAB character (TSV), instead of a comma (CSV), because tab delimited files have a much better chance of not needing to escape the field delimiter within the values, which makes it more likely to be command-line friendly by default.\n\nThe `-x` option lets you parse iCalendar objects other than events if needed. The default value is \"VEVENT\" for events, but other values could be, for example: \"VTODO\", \"VJOURNAL\" \"VFREEBUSY\" \"VTIMEZONE\" \"VALARM\".\n\nThe `-n` option skips external calls to the `date` command which makes the processing much faster and might avoid issues if you don't have a normal `date` command available on your system. Downside is: no ISO timestamps, and no DURATION computation.\n\nThe `-r` option is for creating ics files from tabular files, because why not! This will also take care of converting the ISO timestamps back into the iCalendar format if necessary. This is somewhat of a \"experimental\" feature right now, since there's a lot of options that this could open the door to that we don't support. For now it just creates a bare-bones, minimal ics file with zero metadata.\n\n## Advanced examples\n\n```sh\nicsp -c 'dtstart,summary,duration' calendar.ics \\\n  | grep '2022-06' \\\n  | sort \\\n  | column -t -s $'\\t' \\\n  | less -S\n```\n\nWhat each line does in order:\n\n1. Only show the 'dtstart', 'summary' and 'duration' fields, in that order from the 'calendar.ics' file\n1. Filter to June 2022 only\n1. Sort chronologically\n1. Align columns (using `column` command)\n1. Display result in scrollable area (using `less`` command)\n\n#### Demo commands\n\nCanadian 2023 holidays\n\n```sh\ncurl -s 'https://calendar.google.com/calendar/ical/en.canadian%23holiday%40group.v.calendar.google.com/public/basic.ics' \\\n  | icsp -c dtstart,summary \\\n  | grep 2023 \\\n  | sort \\\n  | column -t -s $'\\t' \\\n  | less -S\n```\n\nMontreal weather forecast in celsius:\n\n```sh\ncurl -s 'https://ical.meteomatics.com/calendar/GC37%2B87%20Montreal%2C%20QC%2C%20Canada/45.503279_-73.586855/en/meteomat.ics' \\\n  | icsp -c dtstart,summary \\\n  | tail -n +2 \\\n  | column -t -s $'\\t'\n```\n\nPhases of the Moon 2023:\n\n```sh\ncurl -s 'https://calendar.google.com/calendar/ical/ht3jlfaac5lfd6263ulfh4tql8%40group.calendar.google.com/public/basic.ics' \\\n  | icsp -c dtstart,summary \\\n  | tail -n +2 \\\n  | grep 2023 \\\n  | sort \\\n  | column -t -s $'\\t'\n```\n\nSpace flight launch calendar:\n\n```sh\ncurl -s 'https://calendar.google.com/calendar/ical/nextspaceflight.com_l328q9n2alm03mdukb05504c44%40group.calendar.google.com/public/basic.ics' \\\n  | icsp -c dtstart,summary,location \\\n  | tail -n +2 \\\n  | sort \\\n  | column -t -s $'\\t' \\\n  | less -S\n```\n\nMerge calendars together:\n\n```sh\ncurl -s 'https://calendar.google.com/calendar/ical/nextspaceflight.com_l328q9n2alm03mdukb05504c44%40group.calendar.google.com/public/basic.ics' \\\n  | icsp -c dtstart,summary,location \\\n  | tail -n +2 \\\n  | sort \\\n  | column -t -s $'\\t' \\\n  | less -S\n```\n\nI like to do these kind of manipulations on the command-line, but remember that you can always load these TSV/CSV files in your favorite programming language for maximum power and flexibility.\n\n## How to get some .ics files to try it out:\n\n\u003cdetails\u003e\u003csummary\u003eFrom Google Calendar\u003c/summary\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/14101189/227659925-cbc204bc-95e0-4bf6-be2e-686ed1fd815f.png\" width=\"320\" alt=\"Step 1\" /\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/14101189/227659927-93e7b7f7-0534-45f9-8e77-c0ef242dd567.png\" width=\"720\" alt=\"Step 2\" /\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eFrom Outlook\u003c/summary\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/14101189/227634762-6229a640-654f-4b2a-8ab5-6acbf4ab7524.png\" width=\"320\" alt=\"Step 2\" /\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/14101189/227635163-3136bc60-656e-42e1-b0f9-87c67a6c85ac.png\" width=\"720\" alt=\"Step 2\" /\u003e\n\n\u003cimg src=\"https://user-images.githubusercontent.com/14101189/227633645-d9fa440e-5380-42c7-bf5d-72dc816f7021.png\" width=\"280\" alt=\"Step 3\" /\u003e\n\u003c/details\u003e\n\n## Motivation\n\nWhile common calendar software (Google, outlook, apple calendars, etc) may provide API access to your calendar data, it is usually a very involved setup that requires changing account configuration or permissions, dealing with authentication / authorization and reading company specific docs.\n\nAt the same time, they all provide very simple import/export features just a few clicks away using the iCalendar (.ics) format from 1998. If we just want to read in data, let's use that instead!\n\n## Reading\n\n#### iCalendar:\n\n- [RFC5545](https://datatracker.ietf.org/doc/html/rfc5545) - iCalendar RFC\n- [icalendar.org](https://icalendar.org/) - iCalendar docs \u0026 tools\n\n#### Working with tabular data on the command-line:\n\n- [CSVs on the CLI](https://bconnelly.net/posts/working_with_csvs_on_the_command_line/)\n- [Command-Line data manipulation](https://planspace.org/2013/05/21/command-line-data-manipulation/)\n- [CLI data scripting intro](https://compphylo.github.io/Oslo2019/Scripting_CLI_Intro/Scripting_CLI_Intro.html)\n- [Singapore university data manipulation intro](https://nusit.nus.edu.sg/technus/data-manipulation-and-more-with-the-command-line/)\n- [More CLI tools](https://github.com/dbohdan/structured-text-tools)\n\n---\n\nPRs, issues and ideas are welcome.\n\nGive the repo a star to show your support!\n\nCrafted by [millisecond studio](https://millisecond.studio/) ❤️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floteoo%2Ficsp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floteoo%2Ficsp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floteoo%2Ficsp/lists"}