# LoreML

LoreML is a markup language for generating random text.

## Installation

```bash
npm i loreml
```

## Usage

```javascript
import LoreML from 'loreml'

const loreml = new LoreML({
  refDate: '2020-01-01T00:00:00.000Z',
})

const text = await loreml.parse(`
  <Root seed="123" locale="en" refDate="2020-01-01T00:00:00.000Z">
      <Document>
          <Text repeat="3">
              <Date when="recent" format="yyyy-MM-dd"/>
              <Paragraph />
          </Text>
      </Document>
  </Root>
`)
```

## LoreML Syntax

### `<Root>`

The root element of the document.

- Attributes
  - `seed` - A seed value for the random number generator.  If not provided, a random seed will be generated.
  - `locale` - The locale of the generated text.  Possible values are:
    - `en` - English (default)
    - `es` - Spanish
    - `fr` - French
    - `de` - German
    - `it` - Italian
  - `refDate` - A reference date used by relative date generation. If not provided, LoreML uses `2020-01-01T00:00:00.000Z` so seeded date output stays deterministic.
- Children
  - `Document`
  - `Template`
  - `Person`
  - `Location`

### `<Template>`

A template is a named block of text that can be reused in the document.

- Attributes
  - `name` - (required) The name of the template.
- Children
  - `Text`

- Example

  ```xml
  <Root>
      <Template name="greeting">
          <Text>
              Greetings {nameVar}
          </Text>
      </Template>
      <Document>
          <Text>
              <UseTemplate ref="greeting" nameVar="Lorem"/>
          </Text>
      </Document>
  </Root>
  ```

### `<Person />`

Generates a random person.

- Attributes
  - `ref` - (required) A reference to the person for later use.
  - `sex` - The sex of the person. If not specified, a random one will be picked.  Possible values are `male` and `female`.

- Example

  ```xml
  <Root>
      <Person ref="person1" />
      <Document>
          <Text>
              <UsePerson ref="person1" />
          </Text>
      </Document>
  </Root>
  ```

### `<Location />`

Generates a random location.

- Attributes
  - `ref` - (required) A reference to the location for later use.

- Example

  ```xml
  <Root>
      <Location ref="location1" />
      <Document>
          <Text>
              <UseLocation ref="location1">
                  <City />
                  <State />
                  <Country />
              </UseLocation>
          </Text>
      </Document>
  </Root>
  ```

### `<Document>`

Denotes the output of a text document.

- Children
  - `Text`

### `<Text>`

A `Text` element can contain any number of **self-closing** elements, other `Text` tags, and also inline raw text.

- Attributes
  - `repeat` - The number of times to repeat the text.  If not provided, the text will be repeated once.
  - `pick` - Sample _N_ children at random.  If not provided, all children will be included.

- Children
  - `Text`
  - `UseTemplate`
  - `UsePerson`
  - `Sentence`
  - `Paragraph`
  - `Date`
  - `UniformInt`
  - `UniformFloat`

### `<UseTemplate />`

Inserts a pre-defined template into the document.

- Attributes
  - `ref` - (required) The name of the template to use.
  - `[varName: string]: string` -  Variables to replace in the template.

- Example

  ```xml
    <Root>
        <Template name="greeting">
            <Text>
                Greetings {nameVar}
            </Text>
        </Template>
        <Document>
            <Text>
            <UseTemplate
                ref="greeting"
                nameVar="Lorem"
            />
            </Text>
        </Document>
    </Root>
  ```

### `<UseLocation />`

Inserts a pre-defined location into the document.  Uses child elements to specify which properties of the location to include.

- Attributes
  - `ref` - (required) The reference of the location to use.

- Children
  - `Address`
  - `Street`
  - `City`
  - `State`
  - `Zip`
  - `Country`

- Example

  ```xml
    <Root>
        <Location ref="location1" />
        <Document>
            <Text>
                <UseLocation ref="location1">
                    <City />
                    <State />
                    <Country />
                </UseLocation>
            </Text>
        </Document>
    </Root>
    ```

### `<UsePerson />`

Inserts a pre-defined person into the document.  Uses child elements to specify which properties of the person to include.

- Attributes
  - `ref` - (required) The reference of the person to use.

- Children
  - `Sex`
  - `Prefix`
  - `FirstName`
  - `LastName`
  - `MiddleName`
  - `FullName`
  - `Email`
  - `Phone`
  - `Address`
  - `Street`
  - `City`
  - `State`
  - `Zip`
  - `Country`

- Example

  ```xml
    <Root>
        <Person ref="person1" />
        <Document>
            <Text>
                <UsePerson ref="person1">
                    <FirstName />
                    <LastName />
                    <Email />
                </UsePerson>
            </Text>
        </Document>
    </Root>
    ```

### `<Sentence />`

Generates a sentence of lorem ipsum text.

- Attributes
  - `min` - The minimum number of words in the sentence.  (Default: 3).
  - `max` - The maximum number of words in the sentence.  (Default: 10).

- Example

  ```xml
  <Root>
      <Document>
          <Text>
              <Sentence min="5" max="10" />
          </Text>
      </Document>
  </Root>
  ```

### `<Paragraph />`

Generates a paragraph of lorem ipsum text.

- Attributes
  - `min` - The minimum number of sentences in the paragraph.  (Default: 3).
  - `max` - The maximum number of sentences in the paragraph.  (Default: 10).

- Example

  ```xml
  <Root>
      <Document>
          <Text>
              <Paragraph min="5" max="10" />
          </Text>
      </Document>
  </Root>
  ```

### `<Date />`

Generates a random date.

- Attributes
  - `when` - The time frame of the date.  Possible values are `recent`, `past`, `soon`, `future`, `anytime`.  (Default: `anytime`).
  - `format` - The format of the date.  See [date-format (npm)](https://www.npmjs.com/package/date-format) for possible values.

- Example

  ```xml
  <Root>
      <Document>
          <Text>
              <Date when="soon" format="yyyy-MM-dd"/>
          </Text>
      </Document>
  </Root>
  ```

### `<UniformInt />`

Generates a uniformly sampled random integer.

- Attributes
  - `min` - The minimum value of the integer.  (Default: 0).
  - `max` - The maximum value of the integer.  (Default: 10).

- Example

  ```xml
  <Root>
      <Document>
          <Text>
              <UniformInt min="5" max="10" />
          </Text>
      </Document>
  </Root>
  ```

### `<UniformFloat />`

Generates a uniformly sampled random float.

- Attributes
  - `min` - The minimum value of the float.  (Default: 0).
  - `max` - The maximum value of the float.  (Default: 10).
  
- Example

  ```xml
  <Root>
      <Document>
          <Text>
              <UniformFloat min="5" max="10" />
          </Text>
      </Document>
  </Root>
  ```