README.md in fugit-0.9.0 vs README.md in fugit-0.9.1
- old
+ new
@@ -2,22 +2,56 @@
# fugit
[](http://travis-ci.org/floraison/fugit)
[](http://badge.fury.io/rb/fugit)
-Time tools for [flor](https://github.com/floraison/flor) and the floraison project.
+Time tools for [flor](https://github.com/floraison/flor) and the floraison group.
+Fugit will probably become the foundation for [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) 4.x
+
+
+## Related projects
+
+### Sister projects
+
+* [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) - a cron/at/in/every/interval in-process scheduler, in fact, it's the father project to this fugit project
+* [flor](https://github.com/floraison/flor) - a Ruby workflow engine, fugit provides the foundation for its time scheduling capabilities
+
+### Similar, somehow overlapping projects
+
+* [chronic](https://github.com/mojombo/chronic) - a pure Ruby natural language date parser
+* [parse-cron](https://github.com/siebertm/parse-cron) - parses cron expressions and calculates the next occurence after a given date
+* [ice_cube](https://github.com/seejohnrun/ice_cube) - Ruby date recurrence library
+* [ISO8601](https://github.com/arnau/ISO8601) - Ruby parser to work with ISO8601 dateTimes and durations
+* ...
+
+
## `Fugit::Cron`
+A class `Fugit::Cron` to parse cron strings and then `#next_time` and `#previous_time` to compute the next or the previous occurrence respectively.
+
+There is also a `#brute_frequency` method which returns an array `[ shortest delta, longest delta, occurrence count ]` where delta is the time between two occurences.
+
```ruby
require 'fugit'
c = Fugit::Cron.parse('0 0 * * sun')
+ # or
+c = Fugit::Cron.new('0 0 * * sun')
-p Time.now # => 2017-01-03 09:53:27 +0900
+p Time.now # => 2017-01-03 09:53:27 +0900
-p c.next_time # => 2017-01-08 00:00:00 +0900
+p c.next_time # => 2017-01-08 00:00:00 +0900
+p c.previous_time # => 2017-01-01 00:00:00 +0900
+
+p c.brute_frequency # => [ 604800, 604800, 53 ]
+ # [ delta min, delta max, occurrence count ]
+
+p c.match?(Time.parse('2017-08-06')) # => true
+p c.match?(Time.parse('2017-08-07')) # => false
+p c.match?('2017-08-06') # => true
+p c.match?('2017-08-06 12:00') # => false
```
Example of cron strings understood by fugit:
```ruby
'5 0 * * *' # 5 minutes after midnight, every day
@@ -37,9 +71,35 @@
'0 0 last * *' # idem
'0 0 -7-L * *' # from the seventh to last to the last day of month at 00:00
# and more...
```
+
+## `Fugit::Duration`
+
+A class `Fugit::Duration` to parse duration strings (vanilla [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler) ones and [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) ones.
+
+Provides duration arithmetic tools.
+
+```ruby
+require 'fugit'
+
+d = Fugit::Duration.parse('1y2M1d4h')
+
+p d.to_plain_s # => "1Y2M1D4h"
+p d.to_iso_s # => "P1Y2M1DT4H" ISO 8601 duration
+p d.to_long_s # => "1 year, 2 months, 1 day, and 4 hours"
+
+d += Fugit::Duration.parse('1y1h')
+
+p d.to_long_s # => "2 years, 2 months, 1 day, and 5 hours"
+
+d += 3600
+
+p d.to_plain_s # => "2Y2M1D5h3600s"
+```
+TODO: continue me
+
## LICENSE
MIT, see [LICENSE.txt](LICENSE.txt)