Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tokenmill/timewords
Multilingual library to easily parse date strings to java.util.Date objects.
https://github.com/tokenmill/timewords
clojure date-parser date-time java natural-language-processing parsing
Last synced: about 1 month ago
JSON representation
Multilingual library to easily parse date strings to java.util.Date objects.
- Host: GitHub
- URL: https://github.com/tokenmill/timewords
- Owner: tokenmill
- License: other
- Created: 2016-12-06T12:30:12.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2019-09-04T08:53:40.000Z (over 5 years ago)
- Last Synced: 2024-05-07T18:28:20.594Z (8 months ago)
- Topics: clojure, date-parser, date-time, java, natural-language-processing, parsing
- Language: Clojure
- Homepage:
- Size: 115 KB
- Stars: 29
- Watchers: 5
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-clojure - timewords
README
# timewords
[](https://clojars.org/lt.tokenmill/timewords)
Library to parse a date string to java.util.Date object. For example:
* "2 weeks from now" -> 2018-11-29T09:52:23.000-00:00
* "28th February 2019" -> 2019-02-28T00:00:00.000-00:00
When the library cannot parse the input string it returns *`nil`*.
More 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``.
The library is designed to support multiple languages. Currently two languages are supported: English and Lithuanian. Default language is English.
# Usage
## Clojure
Add a dependency to your
* *project.clj* - `[lt.tokenmill/timewords "0.5.0"]`
* *deps.edn* - `lt.tokenmill/timewords {:mvn/version "0.5.0"}`
```clojure
(require '[timewords.core :refer [parse]])
=> nil
(parse "2001-01-01")
=> #inst"2001-01-01T00:00:00.000-00:00"
(timewords.core/parse "now")
=> #inst"2016-12-13T09:52:02.000-00:00"
(timewords.core/parse "2 weeks ago")
=> #inst"2016-11-29T09:52:23.000-00:00"
(timewords.core/parse "2 weeks from now")
=> #inst"2016-12-29T09:54:23.000-00:00"
(timewords.core/parse "last monday")
=> #inst"2016-12-12T09:54:23.000-00:00"
(timewords.core/parse "last june")
=> #inst"2016-06-12T09:54:23.000-00:00"
(timewords.core/parse "last spring")
=> #inst"2016-05-12T09:54:23.000-00:00"
(timewords.core/parse "29th February 2016")
=> #inst"2016-02-29T00:00:00.000-00:00"
(timewords.core/parse "29th February 2017")
=> #inst"2017-02-01T00:00:00.000-00:00"
(timewords.core/parse "Sunday, 1st January 2017")
=> #inst"2017-01-01T00:00:00.000-00:00"
(timewords.core/parse "2016 m. gruodžio 22 d. 11:10" nil "lt")
=> #inst"2016-12-22T11:10:00.000-00:00"
```
## Java
As of now the JAR is stored in Clojars, therefore maven is not going to find the artifact.
You should add the repository information to your `pom.xml`:
```xml
clojars.org
http://clojars.org/repo
```
Add a maven dependency to your `pom.xml`:
```xml
lt.tokenmill
timewords
0.4.0
```
```java
import lt.tokenmill.timewords.Timewords;
public static void main(String[] args) {
Timewords timewords = new Timewords();
Date d1 = timewords.parse("2001-01-01");
Date d2 = timewords.parse("2001-01-01", new Date());
Date d3 = timewords.parse("2001-01-01", new Date(), "en");
}
```
Note that `timewords` depends on `org.clojure/clojure` which must be provided.
# Notes
Relative 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`.
Timewords of the form `in monthname` is interpreted as if it refers to the past, i.e. `in December` means `last December`.
Timewords of the form `this monthname` is interpreted as if it refers to the future, i.e. `in December` means `next December`.
Timeword 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`.
Timeword 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.
Timeword 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`.
# TODO
TODO:
- [ ] relative Lithuanian dates.
## License
Copyright © 2019 [TokenMill UAB](http://www.tokenmill.lt).
Distributed under the The Apache License, Version 2.0.