Portable DateTime and Schedule Notation

ptdtsn.txt

Portable DateTime and Schedule Notation


There are two types of PDTSN objects: iterator and check

The iterator allows you to iterate the date and time from start to end
The check checks the conditions against the supplied value

Both objects have an object for a date clause and a time clause.


ITERATOR
	BY
		// Sets the granularity of the iterator
		// For instance using a granularity of DATE = $date->modify('+1 day')
		DATE
			// $date->modify('+1 day')
		YEAR
			// $date->modify('+1 year')
		MONTH
			// $date->modify('+1 month')
		DAY
			// $date->modify('+1 day')
		WEEK
			// $date->modify('+1 week')
		JULIANDAY/DAYOFWEEK
			// $date->modify('+1 day')
		TIME
			// $date->modify('+1 second')
		HOUR
			// $date->modify('+1 hour')
		MINUTE
			// $date->modify('+1 minute')
		SECOND
			// $date->modify('+1 second')
	START
	END
	REVERSE
		// TRUE/FALSE, defaults to FALSE
	FORMAT
		(SEE http://www.php.net/manual/en/datetime.formats.date.php)
	DATE
		// These conditions are compared with $and
		// If you want them to be $or, you must enclose them in an $or object
		DATE
			// Must have a valid date as \DateTime will be instantiated directly with it
			// Can use anything that would work with strtotime()
		YEAR
			// Must be an integer or int[]
			// Can be LEAPYEAR or NOT(LEAPYEAR)
		MONTH
			// Must have a valid month
			// Can use the word or the integer form
		JULIANDAY/DAYOFYEAR
			// Must be between 1 and 365
		DAYOFWEEK
			// Must have a valid day of week
		MONTHDAY
			// Must have a valid month and day.
			// So long as strtotime() can handle it
		COUNT
			// Count must have two elements
			// The first element is a check
				// The check can be one of year, month, week which will match against the current year/month/week
				// If the key does not match any of these, it iterate from start to end counting each match of the value
			// The second one is the matching count
			// The matching count can be any operator except $and as that one doesn't make any sense here since count can only return a single scalar value
			// Or an operator object ie {'$gt': 1}
			
	TIME
		TIME
			// Must be a valid time
		HOUR
			// Using 24 hour format, must be between 0 and 24
		MINUTE
			// Between 0 and 60
		MINUTEOFDAY
			// Between 0 and 1440
		SECOND
			// Between 0 and 60
		SECONDOFHOUR
			// Between 0 and 86,400
		SECONDOFDAY
			// Between 0 and 2,073,600
		COUNT
			// See Interval->Date->Count

CHECK
	VALUE
		=$NOW
		=(string)
	WHEN (see Interval->When)

OPERATORS
	$or/||
	$and/&&
		// The default comparison is $and
	$eq/=
		// If the value of one of the date/time conditions is a scalar, it will use $eq
	$not/!
		// Reverses the condition
	$gt/>
		// Checks if the DateTime is greater than the value
	$lt/<
		// Checks if the DateTime is less than the value
	$in
		// If the value of one of the date/time conditions is an array, it will use $in
	$between
		// The value must be an array. First element is the minimum, second is the max
		// Equates to $value > min && $value < max
	step/%
		// Equates to date/time % $step === 0.
		// Used to get every Nth value


{iterator: {
	'by': 'date',
	'start': 'now - 3 years',
	'end': 'now + 3 years'
	'date': [
		{'dayofweek': 'tuesday'},
		{
			'year': {
				'$between': [2012, 2014]
			}
		},
		{
			'$or': [
				{'year': 2012},
				{'year': 2013},
				{'year': 2014}
			]
		}
	]
}}

This would return an iterator of every Tuesday in 2012, 2013, and 2014. 
ITERATOR says that you are trying to get an iterator. 
BY is the granularity and it is set to the date. 
Some other levels of granularity would be time, hour, second, month, week, year, etc. 
The tokens are case-insensitive. 
Tuesday is a constant and is also case-insensitive.


Below is an example check object


// This checks for US President's elections
// With a hypothetical reporting of election results every other hour between 8 AM and 8 PM
// The actual days were very varied before 1845, so this is just the current law
// See https://en.wikipedia.org/wiki/Election_Day_(United_States) for more info

This is what it looks like as JSON
{'check': {
	'value': 'now',
	'date': [
		{'month': 'november'},
		{'dayofweek': 'tuesday'},
		{'year': {'$gt': 1787}},
		{'year': 'leapyear'},
		{'count': [
			{'month': {'dayofweek': 'tuesday'}},
			1
		]},
		{'count': [
			{'month': {'dayofweek': 'monday'}},
			1
		]}
	],
	'time': [
		{'hour': {'$between': [8, 20]}},
		{'hour': {'step': 2}}
	]
}}

Here's what it looks like as a PHP array
$query = array(
	'check' => array(
		'value' => 'now',
		'date' => array(
			array('month' => 'november'),
			array('dayofweek' => 'tuesday'),
			array('year' => array('$gt: 1787)),
			array('year' => 'leapyear'),
			array('count' => array(
				array('month' => array('dayofweek' => 'tuesday')),
				1
			)),
			array('count' => array(
				array('month' => array('dayofweek' => 'monday')),
				1
			)),
		),
		'time' => array(
			array('hour' => array('between' => array(8, 20))),
			array('hour' => array('step' => 2)),
		),
	),
);

$dtquery = new DateTimeQuery($query);
var_dump($dtquery->isTrue());