# ParSec
## A duration parser and formatter to turn random garbage into program usable times.<br>
## Provides a clear, easy to use interface to parse strings into usable timings<br>
Example:
```js
Parsec('aug3 1920').format('{MONTH-NAME} {DAYS}{DAY-SUFFIX} {YEAR}') 
// August 3rd 1920
```
----
## Documentation Navigation
+ [Installation](https://github.com/fatalcenturion/parsec#installation)
    - [NPM](https://github.com/fatalcenturion/parsec#npm)
    - [Yarn](https://github.com/fatalcenturion/parsec#yarn)

+ [Locales](https://github.com/fatalcenturion/parsec#locales)
    - [Supported](https://github.com/fatalcenturion/parsec#supported-locales)
    - [Planned](https://github.com/fatalcenturion/parsec#planned-locales)

+ [Usage](https://github.com/fatalcenturion/parsec#usage)
    - [ParSec](https://github.com/fatalcenturion/parsec#parsec)
    - [TimeConstruct](https://github.com/fatalcenturion/parsec#timeconstruct)
----
## Installation
### NPM
Installing on NPM is simple, just open your terminal and run:
```
npm install parsec --save
```
### Yarn
to install with Yarn, open your terminal and use:
```
yarn add parsec
```
----
## Locales
### Supported Locales
All languages supported by this module are translated to the best knowledge of the person submitting the translation, this means we are trying to get native speakers of the language to submit translations of time phrases in their local language,
|Language|Native|Supported Since|Translator|
|:------:|:----:|:-------------:|:--------:|
|English|English|0.0.1|Fatalcenturion|

### Planned Locales
This table contains languages which we are planning to implement into the module, but have not managed to do just yet.
If you are a native speaker of any of the languages below and would like to help translate, please get in touch so we can send you a translation package.

|Language|Native|
|:------:|:----:|
|German|Deutsch|
|French| français|
|Spanish|español|
|Portuguese|português|

### Suggest a Locale
To suggest a Locale for ParSec, please open an issue and use the "Locale" tag informing us of the locale you wish to add
----
## Usage

## ParSec
Importing the module:

```js
const ParSec = require('parsec');
```

Getting started:

This module is a hybrid function-object, this means that the module can be called by running both:
```js
let parsed = ParSec('1 minute, 30 seconds and 145 milliseconds');
```
And:
```js
let parsed = ParSec.parse('1 minute, 30 seconds and 145 milliseconds');
```
> Note: in both cases here, ``parsed`` is an instance of ``TimeConstruct``.<br>
> ``TimeConstruct`` is a custom class built to provide detailed information about your parsed results.<br>
> [Read the documentation on ``TimeConstruct`` for more information](https://github.com/fatalcenturion/parsec#timeconstruct)

Values:
> 


> `self`:<br>
> > Parameters:<br>
> > inputString: `String`<br><br>
> > Description: Formats the provided string into an instance of `TimeConstruct`.<br><br>
> > Usage: 
```js
ParSec(<inputString>)
```

<br>

> `format`:<br>
> > Parameters<br>
> > inputString: `String`<br><br>
> > Description:<br>
> > Formats the provided string using internal values
> > (Internal version of ParSec(string))

> `parse`:<br>
> > Parameters<br>
> > inputString: `String`<br><br>
> > Description:<br>
> > Formats the provided string into an instance of `TimeConstruct`
> > (Internal version of ParSec(string))

----

## TimeConstruct
Layout:

Values:
> locale: `String`<br>
> milliseconds: `Number`<br>
> seconds: `Number`<br>
> minutes: `Number`<br>
> hours: `Number`<br>
> days: `Number`<br>
> weeks: `Number`<br>
> months: `Number`<br>
> years: `Number`<br>

Methods:
> `format`:<br>
> > Parameters<br>
> > inputString: `String`<br><br>
> > Description:<br>
> > Formats the provided string using internal values
> > (Internal version of ParSec(string))

> `into`:<br>
> > Parameters<br>
> > inputString: `String`<br><br>
> > Description:<br>
> > Formats the provided string, converting all internal values to the largest specified value
> > (Internal version of ParSec(string))

### More coming soon....