# The Gritty Details

## Problem Statement
Create a typescript parser for a string based relative date language. The application will resolve from the Relative Date Format (RDF) to a pair of UNIX timestamps

## Action Plan
1. Define the RDF format and create a suitable grammar
2. Using ANTLR's .g4 file format, formalize the RDF grammar and produce a lexer/parser which is usable in typescript.
3. Create multiple intermediate AST's which can be traversed step by step to reduce a raw RDF string to the final UNIX timestamp output (each phase is described in more detail below)
4. Output the final UNIX start/end time to the user

## Requirements
1. RDF must be capable of expressing relative time concepts anchored on any fixed point in time; past, present or future.
2. RDF must support the concept of now, or the current time, as an absolute reference to which relative times can be anchored.
3. The application must be able to quickly determine invalid RDF strings and provide meaningful feedback to the user about the incorrect format.
4. Output must be consistent

## Step 1: Defining RDF
The crux of this project is to create an approachable language for representing relative time concepts in a single string. The responsibility of representing these concepts will be divided among three primary modes:

**Range Mode**  
Represents a period between two explicitly resolvable timestamps

**Trail Mode**  
Represents a period of time immediately preceding and explicitly resolvable timestamp

**Period Mode**  
Represents the start and end of a period of time within which an explicitly resolvable timestamp resides

Upon defining these modes, it became immediately apparent that some provided information in the string would be _resolvable_, while other inputs would depend on these resolvable inputs to anchor them in time.

## Creating a Grammar
Using the basic structure outlined above, a grammar was created which could completely express the concepts of relative time and be reduced down into a single pair of timestamps

## Walking the Parse Tree
In order to produce the final result, the RDF parse tree will be walked multiple times, with each subsequent traversal reducing the graph towards the final result. Traversal will take place in 3 distinct phases:

#### Phase 1: Compute Resolvable Expressions
Many of the inputs in an RDF string will be fully resolvable right out of the gate, that is to say they require no additional information in order to be reduced to a single timestamp. The first walk of the tree will find and replace all resolvable expressions with their equivalent timestamps

Phase 1 will read the CST produced by ANTLR and output an AST will all resolvable expressions fully resolved

#### Phase 2: Compute Relative Expressions
Some inputs can be given in a format that is are only sensible when compared to a static, fully resolved reference timestamp. Such inputs may be relative to a resolvable expression, and as such can only be handled once the resolvable expressions have been handled

Phase 2 will read the AST produced by Phase 1 and output an AST with all expressions resolved (including relative expressions)

#### Phase 3: Compute Time Range
Now that all inputs have been fully resolved into either timestamps (or time deltas), the final step is to use the indicated mode to generate a timestamp range from the inputs and return it to the user.

Phase 3 will read the AST produced by Phase 2 and return a pair of UNIX timestamps indicating the start and end time of the given RDF at the time of evaluation.