{"id":26503104,"url":"https://github.com/quantiusbenignus/dated","last_synced_at":"2026-04-10T21:11:54.647Z","repository":{"id":219372010,"uuid":"598344967","full_name":"QuantiusBenignus/dated","owner":"QuantiusBenignus","description":"ZSH exoskeleton for the command line \"date\" utility. Support free-form time references.","archived":false,"fork":false,"pushed_at":"2023-02-22T19:18:50.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-01-27T01:58:16.871Z","etag":null,"topics":["command-line","command-line-tool","date","datetime","future","linux","nlp","parser","shell-script","text-processing","time","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/QuantiusBenignus.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-02-06T23:01:55.000Z","updated_at":"2024-01-27T01:58:19.701Z","dependencies_parsed_at":"2024-01-27T01:58:17.513Z","dependency_job_id":"1b034a4f-d6b7-48a6-8765-57198b312f8b","html_url":"https://github.com/QuantiusBenignus/dated","commit_stats":null,"previous_names":["quantiusbenignus/dated"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantiusBenignus%2Fdated","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantiusBenignus%2Fdated/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantiusBenignus%2Fdated/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantiusBenignus%2Fdated/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QuantiusBenignus","download_url":"https://codeload.github.com/QuantiusBenignus/dated/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244676317,"owners_count":20491827,"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":["command-line","command-line-tool","date","datetime","future","linux","nlp","parser","shell-script","text-processing","time","zsh"],"created_at":"2025-03-20T18:58:06.947Z","updated_at":"2026-04-10T21:11:49.610Z","avatar_url":"https://github.com/QuantiusBenignus.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `dated`, a `date -d` on steroids\n## ZSH exoskeleton for the command line \"date\" utility\n### *Expand the ability of `date` to handle natural language time references (in English)*, using only the shell built-ins.\n\nThe command line utility `date` from [GNU coreutils](https://www.gnu.org/software/coreutils/manual/html_node/date-invocation.html) is familiar to everyone who uses the Linux command line.\nWhen used with the command line flag `-d` it can parse strings which contain properly formatted datetime constructs and if successful, output the resulting datetime to the standard output, formatted as per additional formatting flags if supplied.\n\nSo `date -d \"next thursday 8:30 pm\"` will output something like \"Thu 09 Feb 2023 08:30:00 PM\"\n\n**Question: Can `date` be made a bit more \"intelligent\" by wrapping it in a command line preprocessor, based only on the built-ins available to the Linux shell (for example bash, or better yet ZSH)?**\n\nIn other words, can it **not explode** if the string was instead: `\"Two years from now, on halloween, at 730 in the morning\"`?\n\nThis repository is an attempt to answer **Yes**  to the above question. The `dated` command line utility is written in and for `zsh` and uses zsh built-in machinery (almost exclusivelly) before handing the preprocessed text to `date -d`.   So, if called at the time of this writing, \n```\ndated \"Two years from now, on halloween, at 730 in the morning\"\n```  \nwill respond with `Fri 31 Oct 2025 07:30:00 AM EDT` ,\n\nor even for the floating Thanksgiving or Easter:\n```\ndated \"on Thanksgiving day in 2040 at 8 in the evening\" \n```\nthe output will be `Thu 22 Nov 2040 08:00:00 PM EST` \nPlease, see the help `dated -h or date d --help` for more examples.\n```\n SYNOPSIS: dated [--help|-h|] ...\u003cstring\u003e [formating options of date]\n\n   - 'dated \u003cstring\u003e' Parse \u003cstring\u003e to a valid time reference and send to 'date -d'\n   - 'dated -h|--help' will print this text\n   - any and all additional arguments are passed as-is to 'date -d' to control formating \n\nThe text in \u003cstring\u003e is parsed and formated into a valid datetime input for 'date -d'.\nIt is quite difficult for computers to parse our spoken time references and using only built-in tools\n(i.e. date -d from coreutils) presents a huge challenge when parsing arbitrary datetime text.\nThere are dedicated, complex NLP tools that work better but they are not perfect either.\n\nEXAMPLES:\n\"Set for Tuesday\"       - this is valid.\n\"for 2023/5/24 at 8pm\"   - also OK.\n\"March the 3rd in the evening.\"  - is OK\n\"on March 16 at 7 in the morning in a couple of years\" - OK\n\"on New years eve, 10 years from now\" - OK\n\"two years from now on halloween at 730 in the morning\"  - works too\n\"3rd of March 2024 at 23 hours 13 minutes\" - OK\n       ( \"...for next week\"\nAlso   | \"...in 3 hours\"\nvalid: { \"...tomorrow morning\"  (see source code for \"morning\" \u0026 other adjustable definitions)\n       | \"...in 33 hours and 5 minutes\"\n       ( \"...January 23 quarter past 7 in the evening\nCustom:  \"...at the usual time\" allows privacy and customization (see code for ideas)\nIn some edge cases, successful parsing gives incorrect datetime. Some practice needed to avoid those\n```\n\n## But WHY?\n\nThe problem this was built to solve can be easily explained by looking at [Spoken](https://github.com/QuantiusBenignus/Spoken), a set of zsh scripts to record Joplin text notes and to-do's via speech, from the microphone. The `td` utility in the repository records audio from the microphone, transcribes it to text using whisper.cpp, a derivative of Open AI's Wisper and then parses the transcribed, free-form text for a datetime reference so that it can set an automatic notification alarm for the Joplin to-do task.  This is performed by using the code functionality of `dated`. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantiusbenignus%2Fdated","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantiusbenignus%2Fdated","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantiusbenignus%2Fdated/lists"}