ekinhbayar/intervalparser

Interval Parser - WIP

IntervalParser

This is a work in progress.

---

This library provides three classes:

1. IntervalFinder, finds time intervals and any leading/trailing data, returns it as a TimeInterval object.

IntervalFinder::find(string $input, int $flags) : TimeInterval

2. Parser, takes a string and returns it as a DateInterval after passing it through the 3# method below.

Parser::parse(string $input): \DateInterval

3. Normalizer, finds and replaces non-strtotime-compatible abbreviations with compatible ones. It does not accept leading data, though it will return trailing data and already compatible abbreviations intact.

Normalizer::normalize(string $input): string

---

Allowed flags for IntervalFinder::find method are:

class IntervalFlags
{
    const INTERVAL_ONLY      = 0b00000000;
    const REQUIRE_TRAILING   = 0b00000001;
    const REQUIRE_LEADING    = 0b00000010;
    const MULTIPLE_INTERVALS = 0b00000100;
}

IntervalFinder takes a ParserSettings object that allows you to set which separators to use, defaults being:

string $leadingSeparationString = 'in',
bool $keepLeadingSeparator = false,
int $multipleSeparationType = self::SYMBOL,
string $multipleSeparationSymbol  = ',',
string $multipleSeparationWord = 'foo'

---

The TimeInterval is a value object that represents an interval of time. It is pretty much a DateInterval that holds extra information:

  int $intervalOffset
  int $intervalLength
  DateInterval $interval
  string $leadingData
  string $trailingData

---

Installation

$ composer require ekinhbayar/interval-parser

Basic usage

/**
 * Some other example inputs:
 *
 * foo in 7 weeks 8 days
 * 9 months 8 weeks 7 days 6 hours 5 minutes 2 seconds baz
 * remind me I have 10 minutes in 2 hours please
 *
 */
$trailing = '7mon6w5d4h3m2s bazinga!';
$leading  = 'foo in 9w8d7h6m5s';
$both = 'foo in 9d8h5m bar';
$onlyInterval = '9 mon 2 w 3 m 4 d';

# Set ParserSettings for IntervalFinder
$settings = new ParserSettings("in", false);
$intervalFinder = new IntervalFinder($settings, new Normalizer());

$intervalAndTrailing = $intervalFinder->find($trailing, IntervalFlags::REQUIRE_TRAILING);
var_dump($intervalAndTrailing);

$intervalAndLeading = $intervalFinder->find($leading, IntervalFlags::REQUIRE_LEADING);
var_dump($intervalAndLeading);

$intervalWithBoth = $intervalFinder->find($both, IntervalFlags::REQUIRE_TRAILING | IntervalFlags::REQUIRE_LEADING);
var_dump($timeIntervalWithBoth);

$intervalParser = new Parser(new Normalizer());

$dateInterval = $intervalParser->parse($onlyInterval);
var_dump($dateInterval);

# Multiple Intervals

# 1. Comma Separated
$multiple = 'foo in 9d8h5m bar , baz in 5 minutes, foo in 2 days 4 minutes boo, in 1 hr, 10 days';
$multipleIntervals = $intervalFinder->find($multiple, IntervalFlags::MULTIPLE_INTERVALS);
var_dump($multipleIntervals);

# 2. Separated by a defined-on-settings word

$settings = new ParserSettings("in", 1, ',', 'then');
$intervalFinder = new IntervalFinder($settings);

$wordSeparated = 'foo in 9d8h5m bar then baz in 5 minutes then foo in 2 days 4 minutes boo then in 1 hr then 10 days';
$wordSeparatedIntervals = $intervalFinder->find($wordSeparated, IntervalFlags::MULTIPLE_INTERVALS);
var_dump($wordSeparatedIntervals);

---

Thanks a ton to PeeHaa, DaveRandom, bwoebi and pcrov for everything they made me learn and for all their help! :-)

intervalparser's Issues

Split up the interval parser

When looking at IntervalParser::findInterval() my first instinct is that the stuff in there should be split up into different classes.

Maybe something like:

• Parser
• LeadingParser
• TrailingParser
• BothParser

Cannot think of better names atm. Also not sure if it makes sense what I just said. Will give it some more thought.

Optional parameters should always be last in signatures

Currently the signature of the constructor of the IntervalParser\TimeInterval has a required parameter after optional parameters:

__construct(int $intervalOffset, int $intervalLength, string $leadingData  = null, string $trailingData = null, $interval)

This effectively makes the two optional parameters mandatory, because there is no way to not pass them in resulting in having to pass nulls when it is not needed. E.g.:

new TimeInterval(7, 24, null, null, new DateInterval());

while you could just pass:

new TimeInterval(7, 24, new DateInterval());

if the optional parameters are last.

Support multiple intervals

Handle the case when the input is expected to have multiple intervals, each optionally having leading and/or trailing data.

What if I told you we could support both relative/fixed formats?

Just an idea but... what do you think about making this library support all kinds of formats? Currently it is mainly for intervals but wouldn't it be great if this is literally a TimeParser (or DateTimeParser)?
See Compound Formats and Relative Formats

Unit tests

This task is very important. Before improvement, need to have a test case, because that way we will be sure that nothing is broken 😄

See https://phpunit.de/ for more details.

I can help with the writing and the organization run automatically on https://travis-ci.org/

Improve overall API

This library was created out of my own autodidactic efforts, so it's highly likely that there are mistakes and lots of room for improvement. Feel completely free to suggest and PR! However I'd really appreciate explicit explanations on the "why" and "how"s of anything you may suggest :)

Also, currently this has no tests at all :( Having some would be really a great improvement.

Will this library fully support strict types?

I see that the base exception declares strict types, but the other classes don't.

Will this library require strict types internally?

Allow setting custom separators

Currently IntervalParser expects the leading data to be separated by "in" like foo in 3 minutes 30 seconds. Having a ParserSettings to set the separators would be nice.