{"id":13998105,"url":"https://github.com/JettChenT/timeblok","last_synced_at":"2025-07-23T05:32:28.126Z","repository":{"id":65146822,"uuid":"583695383","full_name":"JettChenT/timeblok","owner":"JettChenT","description":"The programming language for calendars","archived":false,"fork":false,"pushed_at":"2023-05-22T14:47:35.000Z","size":856,"stargazers_count":97,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-18T14:21:58.161Z","etag":null,"topics":["calendar","compiler","dsl","language","productivity","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JettChenT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-12-30T15:50:21.000Z","updated_at":"2024-11-04T01:16:12.000Z","dependencies_parsed_at":"2023-01-01T00:35:20.824Z","dependency_job_id":"97139666-3990-4977-8314-a90a3e3f37ab","html_url":"https://github.com/JettChenT/timeblok","commit_stats":{"total_commits":118,"total_committers":1,"mean_commits":118.0,"dds":0.0,"last_synced_commit":"db3a99866b0d51ab44834bea30a3e661247ca191"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JettChenT%2Ftimeblok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JettChenT%2Ftimeblok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JettChenT%2Ftimeblok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JettChenT%2Ftimeblok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JettChenT","download_url":"https://codeload.github.com/JettChenT/timeblok/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227048751,"owners_count":17723255,"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":["calendar","compiler","dsl","language","productivity","rust"],"created_at":"2024-08-09T19:01:23.942Z","updated_at":"2024-11-30T00:31:05.542Z","avatar_url":"https://github.com/JettChenT.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# TimeBlok\n\n![Crates.io](https://img.shields.io/crates/v/timeblok)\n\u003ca href=\"https://discord.gg/MXxsyAaeFg\"\u003e\u003cimg alt=\"discord invitation link\" src=\"https://dcbadge.vercel.app/api/server/MXxsyAaeFg?style=flat\"\u003e\u003c/a\u003e\n\n```bash\ncargo install timeblok-cli  # install timeblok \ntimeblok -no            # create\u0026write a new blok file, and open it in your calendar app! \n```\n\n## What is TimeBlok? \nTimeBlok is a simple, declarative DSL that combines the versatility and extensibility of plain text \nwith the convenience of digital calendars for \npersonal calendar planning. \n\nInspired by Cal Newport's [Text File Time Blocking](https://www.calnewport.com/blog/2020/03/16/text-file-time-blocking/), \nTimeBlok offers a minimalistic syntax for organizing your schedule within plain text files, \nas well as the ability to compile to .ics files for use in any calendar application.\n\n[Join](https://discord.gg/MXxsyAaeFg) our discord server!\n\n## Examples\n### Daily planning\nThis is the simplest use case\n```\n2023-1-1\n7:30am wake up \u0026 eat beakfast\n8am~11:30 work on TimeBlok\n- Write Technical Documentation\n2pm~6pm Study for exams\n8pm~10pm Reading\n- Finish an entire book\n```\nWhen compiled into an .ics file, this could be imported into your calendar.\n![](./media/dayplan.png)\n\n### Monthly planning\n```\n/region CN                                        // Sets the region to China\n2023-1-                                           // Locks in the following events to 2023-1\n{--1~--10 and CNworkday}                          // workdays from jan 1 to jan 10 in China\n7:30am wake up to a new day\n10am ~ 11am work on EvilCorp\n\n{sun}\n4pm weekly review                                 //weekly review every sunday\n\n--11\n8am~10am Resign from EvilCorp\n- Make sure you still have access to the servers\n\n\n-2-                                               // This overrides the month information from line 1.\n--1\n3pm~4pm Initiate operation \"Hack the planet\"\n```\n\nAfter resolving, this could be imported into your calendar:\n![](media/monthlyplan.png)\n\n## Installation\nCurrently, a [Rust](https://www.rust-lang.org/) installation\nis required.\n\nInstalling from cargo:\n```bash\n$ cargo install timeblok-cli\n```\n\n\n## Usage\nExporting to file:\n```bash\n$ timeblok input.txt -f output.ics\n```\n\nExporting \u0026 opening in default calendar application:\n```bash\n$ timeblok input.txt -o\n```\n\nCreate a new plan file and open it in your calendar app:\n```bash\n$ timeblok --new -o\n$ timeblok -no # shorthand\n```\n\nHelp:\n```bash\n$ timeblok --help\n```\n\n## Integrations\n- VSCode (Syntax Highlighting) [marketplace](https://marketplace.visualstudio.com/items?itemName=JettChenT.vscode-timeblok)\n\n## Specs \nThe TimeBlock language the following statements:\n- Event\n- Occasion\n- Notes\n- Filters\n- Commands\n\n`Occasion` is any single line that describes a point in time, usually dates in `YYYY-MM-DD` format.\nIt can be a date, a time, or a date and time.\nOccasions will inherit the not specified fields from the closest previous occasion.\nThe first occasion inserted into scope will be the creation date of the target file.\nE.g. If the previous occasion is `2024-3-`, then `--3` will be interpreted as `2024-3-3`.\n\nAn `Event` is a line of text that starts with an `Occasion` or `Range` and is followed by text indicating the event's name.\n\nA `Note` just a line of text, if it occurs after an Event, it is considered a note for that event, which will correspond to the \n`DESCRIPTION` field of an ics entry.\n\nA `Range` is simply a pair of Occasions, separated by a `~`, indicating, well, a time-range.\n\nA `Command` is a line of text that starts with a `/` and is followed by a command name and arguments, allowing for an extra level of extensibility.\n\n#### Filters\n`Filters` are a special type of statement that can be used to filter out dates, events, numbers in a specified range.\nFilters can be nested and combined to represent complex logic and recurring events.\nSyntactically, they are enclosed in curly braces `{}`.\n\nIn the process of resolving, filters binds to the last specified `Occasion`, iterates through all possible values that fits the occasion, \nand selects those that fits the criteria for the filter.\n\nFor example, consider the following filter:\n```\n-2-\n{--1~--10 and workday}\n```\nThis filter bounds to the occasion `-2-`, in which the year of the occasion could be inherited from previous occasions(by default the creation date of the file)\n, and the date is unspecified.\nThus, the filter will iterate through all possible dates in February. \nSince the two sub-filters are joined by an `and` clause, the filter will only select those dates that are both in the range `--1~--10` and are workdays.\n\nThe following filters are currently supported:\n- Basic logic filters: `and`, `or`, `not`\n- Range filters: filters all dates in a range, eg. `--1~--10` filters all dates with day value 1 to 10 in the inferred year and month\n- Day-of-week filters: `workday`, `weekend`,  `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` (shorthand `mon` ~ `sun` is also supported)\n- \"Flexible date filters\": basically a shorthand for range filters, eg. `--{1~10}` is equivalent to `--1~--10`\n\n#### Commands (Experimental)\nFormat: `/command_name [arg1] [arg2] ...`\n\nCurrently, commands are statements that can make changes to the scope, or namespace, of the program, or perform arbitrary operations.\nIn the future, commands will also support creations of `OCCASIONS` and `EVENTS`, as well as a plugin system.\n\nCurrently available commands include:\n- `/region [region_name]`: sets the region for resolving workdays based on the amazing [workalendar](https://github.com/workalendar/workalendar) project. For a reference of the names of all supported regions, see [here](https://github.com/JettChenT/workalendar-hub/tree/main/workingdays). Note: currently only [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) and [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes(eg. CN, US) are supported, but we will support more flexible region names in the future.\n- `/set [key] [value]`: sets a name in the namespace to a value. This is useful for for creating custom filters. eg. `/set semester {-2-17~-6-30}`\n- `/print [key]`: prints the value of a name in the namespace. \n- `/tz [timezone]` `/timezone [timezone]`: sets the timezone for the output ics file. eg. `/tz utc`\n- `/t [todo]`: creates a todo event. eg. `/t buy milk`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJettChenT%2Ftimeblok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJettChenT%2Ftimeblok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJettChenT%2Ftimeblok/lists"}