{"id":13801303,"url":"https://github.com/tokenmill/timewords","last_synced_at":"2025-04-22T17:30:26.382Z","repository":{"id":138584510,"uuid":"75729366","full_name":"tokenmill/timewords","owner":"tokenmill","description":"Multilingual library to easily parse date strings to java.util.Date objects.","archived":false,"fork":false,"pushed_at":"2019-09-04T08:53:40.000Z","size":118,"stargazers_count":29,"open_issues_count":6,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-07T18:28:20.594Z","etag":null,"topics":["clojure","date-parser","date-time","java","natural-language-processing","parsing"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokenmill.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":"2016-12-06T12:30:12.000Z","updated_at":"2024-03-28T20:26:25.000Z","dependencies_parsed_at":"2023-04-15T12:01:22.569Z","dependency_job_id":null,"html_url":"https://github.com/tokenmill/timewords","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/tokenmill%2Ftimewords","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Ftimewords/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Ftimewords/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Ftimewords/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokenmill","download_url":"https://codeload.github.com/tokenmill/timewords/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250287337,"owners_count":21405588,"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":["clojure","date-parser","date-time","java","natural-language-processing","parsing"],"created_at":"2024-08-04T00:01:21.393Z","updated_at":"2025-04-22T17:30:26.013Z","avatar_url":"https://github.com/tokenmill.png","language":"Clojure","readme":"\u003ca href=\"http://www.tokenmill.lt\"\u003e\n      \u003cimg src=\".github/tokenmill-logo.svg\" width=\"125\" height=\"125\" align=\"right\" /\u003e\n\u003c/a\u003e\n\n# timewords\n\n[![Clojars Project](https://img.shields.io/clojars/v/lt.tokenmill/timewords.svg)](https://clojars.org/lt.tokenmill/timewords)\n\nLibrary to parse a date string to java.util.Date object. For example:\n\n* \"2 weeks from now\" -\u003e 2018-11-29T09:52:23.000-00:00\n* \"28th February 2019\" -\u003e 2019-02-28T00:00:00.000-00:00\n\nWhen the library cannot parse the input string it returns *`nil`*.\n\nMore formally, from four types of temporal expressions: *time*, *duration*, *interval*, and *set*; only one type is of interest: *time*. Also, *time* type can be divided into two subtypes: fuzzy (e.g. last Sunday) and absolute (1st of January, 2019). To parse a fuzzy time string a *reference time* (i.e. a `java.util.Date object`) is required. By default, reference time is ``now``. \n\nThe library is designed to support multiple languages. Currently two languages are supported: English and Lithuanian. Default language is English.\n\n# Usage\n \n## Clojure\n\nAdd a dependency to your\n* *project.clj* - `[lt.tokenmill/timewords \"0.5.0\"]`\n* *deps.edn* - `lt.tokenmill/timewords {:mvn/version \"0.5.0\"}`\n\n```clojure\n(require '[timewords.core :refer [parse]])\n=\u003e nil\n(parse \"2001-01-01\")\n=\u003e #inst\"2001-01-01T00:00:00.000-00:00\"\n(timewords.core/parse \"now\")\n=\u003e #inst\"2016-12-13T09:52:02.000-00:00\"\n(timewords.core/parse \"2 weeks ago\")\n=\u003e #inst\"2016-11-29T09:52:23.000-00:00\"\n(timewords.core/parse \"2 weeks from now\")\n=\u003e #inst\"2016-12-29T09:54:23.000-00:00\"\n(timewords.core/parse \"last monday\")\n=\u003e #inst\"2016-12-12T09:54:23.000-00:00\"\n(timewords.core/parse \"last june\")\n=\u003e #inst\"2016-06-12T09:54:23.000-00:00\"\n(timewords.core/parse \"last spring\")\n=\u003e #inst\"2016-05-12T09:54:23.000-00:00\"\n\n(timewords.core/parse \"29th February 2016\")\n=\u003e #inst\"2016-02-29T00:00:00.000-00:00\"\n(timewords.core/parse \"29th February 2017\")\n=\u003e #inst\"2017-02-01T00:00:00.000-00:00\"\n(timewords.core/parse \"Sunday, 1st January 2017\")\n=\u003e #inst\"2017-01-01T00:00:00.000-00:00\"\n\n(timewords.core/parse \"2016 m. gruodžio 22 d. 11:10\" nil \"lt\")\n=\u003e #inst\"2016-12-22T11:10:00.000-00:00\"\n```\n\n## Java\n\nAs of now the JAR is stored in Clojars, therefore maven is not going to find the artifact.\nYou should add the repository information to your `pom.xml`:\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003eclojars.org\u003c/id\u003e\n        \u003curl\u003ehttp://clojars.org/repo\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n```\n\nAdd a maven dependency to your `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003elt.tokenmill\u003c/groupId\u003e\n    \u003cartifactId\u003etimewords\u003c/artifactId\u003e\n    \u003cversion\u003e0.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n```java\nimport lt.tokenmill.timewords.Timewords;\n\npublic static void main(String[] args) {\n    Timewords timewords = new Timewords();\n    Date d1 = timewords.parse(\"2001-01-01\");\n    Date d2 = timewords.parse(\"2001-01-01\", new Date());\n    Date d3 = timewords.parse(\"2001-01-01\", new Date(), \"en\");\n}\n```\nNote that `timewords` depends on `org.clojure/clojure` which must be provided.\n\n# Notes\n\nRelative dates that can be understood as a time period, e.g. `last December` are rounded to the beginning of the period, e.g. `last December` translates to `2016-12-01T00:00:00Z`.\n\nTimewords of the form `in monthname` is interpreted as if it refers to the past, i.e. `in December` means `last December`.\n\nTimewords of the form `this monthname` is interpreted as if it refers to the future, i.e. `in December` means `next December`.\n\nTimeword which is only a name of a weekday, e.g. `Monday`, is interpreted as if it refers to the past, i.e. `Monday` means the same as `last Monday`.\n\nTimeword of the form `next weekday` means the first day in the future which which weekday is the one mentioned, e.g. `next Monday` means the first Monday to come. If today is Monday and we are parsing `next Monday` then it means a date after 7 days. \n\nTimeword of a form `this weekday`, e.g. `this Monday`, is interpreted as if it refers to the future, i.e. `this Monday` means the same as `next Monday`.\n\n# TODO\n\nTODO: \n- [ ] relative Lithuanian dates.\n\n## License\n\nCopyright \u0026copy; 2019 [TokenMill UAB](http://www.tokenmill.lt).\n\nDistributed under the The Apache License, Version 2.0.\n","funding_links":[],"categories":["Date and Time"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenmill%2Ftimewords","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokenmill%2Ftimewords","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenmill%2Ftimewords/lists"}