Template

This is a documentation on how templates and generators will be created. It will literally be a text that will be parsed

Introduction

Creating data

This is the core of the template, it relies on parsing generator to select from. To create a generator, use the datatype: list_name keyword, and then the values in indentation. An example below is a list.

Below is a basic generator that contains a list called name

list: names
  James
  John
  Doe

Generating values

We use square brackets to run the generators. It will parse the content based on the data type when used directly like this

list: names
  James
  John
  Doe

---
Hi, I am [names].

This will randomly select a name from one of the list. It should be noted that data will will not appear in the result. Hence, we get something like this

Result

Hi, I am James

--- is an optional demarcation line, to be used only once in the document. Anything above this line is hidden in the result but available to use anywhere in the template

Lists

List with odds This is the most fundamental data type. We have shown you how to create a basic list, but what if you want to add odds to your list? By default, every item has an odd of 1, but you can change the odds of any item in the list

list: names
  James
  John^20
  Doe

---
Hi, I am [names].

In the example above, the odds of picking James is 20 out of 22

Result

Hi, I am John

Inline list

For one time use, you can nest your list

Go straight and take the second {right|left}, it's the first {shop^3|house} that you see

As you can see, you can add odds to the inline list. This will produce something like this

Result

Go straight and take the second right, it's the first shop that you see

You can also use inline list to "merge" two list, sort of. For example

This country is know to contain many species of {[animal]|[plant]}

In this scenario, three things will happen

A random animal will be selected, e.g. Dogs
A random plant will be selected, e.g. Soy
This will result in a inline list like this {Dogs|Soy} from which one of them is picked

Result

This country is know to contain many species of Dogs

Grammar

Things like plurality or articles can be challenging, for example

There is {1|2|3} [fruit] on the table

This might produce something like this

Result

There is 3 apple on the table

Doesn't sound right, if only we could fix the grammar? (is=> are), (apple=>apples). This can be done with dynamic values meant to obey grammatical rules

There {is} {1|2|3} {[fruit]{s}} on the table

{is} will respect grammatical rules, and using {s} will pluralise the words accordingly

Result

There are 2 apples on the table

info

It should be noted that the use of {s} will pluralise accordingly, even for irregular plurals

I have {a} [animal] and {1|2|3} child{s}

Note how child became children and not childs. Note how {a} is also transformed to "an" to match alpaca. If the alpaca is plural {a} will be transformed to some.

Result

I have an alpaca and 3 children.

Ranges

As you can see so far, we've been dealing with small numbers like 1 to 3, {1|2|3}, what if it's a range between 1 and 1000? Surely, we can't write all of the out, well, you don't have to.

Certain recognised range, like numbers can be parsed directly using -

So far, I have counted {5-100} birds.

This will generate any value between 5 and 100 inclusively, meaning it may produce 5 or 100 as well as anything between.

Result

So far, I have counted 52 birds.

It also supports alphabets

{a-z}: lower cases
{A-Z}: upper cases
{a-Z}: lower and upper cases

External data

Similar to ranges or grammar values, there are some inbuilt generators for commonly occurring list, like days of the week, months, colours, elements on the periodic table etc.

There are some community provided generators too, that you can download. Once you get the hack of this, you might also

My favourite colour is {use:colors}

Result

My favourite colour is red

Creating generators

A generator must contain only data.

friends.generator
list: friends
  Chandler
  Joey
  Monica
  Phoebe
  Rachel
  Ross

Today, I ran into one of those friends actors, you know the person that played {use:friends}

friends = {use:friends}
---
Today, I ran into one of those friends actors, you know the person that played [friends]

Result

Today, I ran into one of those friends actors, you know the person that played Monica

Apart from being reused, it allows complex data manipulation. You will find out later in nested list

Transform

You can modify the result by using certain transform, this is accessed using .

There are some [animal.pluralForm] in the garden

Result

There are some dogs in the garden

The value transforms the word (dog) to it's plural form. The following are the supported transforms

Cases

Modifies casing of the word, handles different capitalisations

He shouted, [action.upperCase] and I obeyed

This would transform the word to uppercase

Result

He shouted, GO and I obeyed

Other sample includes

lowercase
UPPERCASE
Sentence case
kebab-case
Titlecase
PascalCase
camelCase
snake_case

Sex

female e.g. lioness
male

Tense

simplePast
simplePresent
simpleFuture
continuousPast, ...
perfectPast ...
perfectContinuousPast ...

Functions

You've already seen this already, for example pluralForm. Another important function is the select function, that can be used to modify what is returned.

selectOne: returns a single item
selectMany (n, connector?): returns n items and joins them with the connector. Default connector is "and"
selectUnique (n, connector?): similar to selectMany, but ensures that all results are unique

It should be noted that you can chain compatible functions

I am considering getting a pet, and my top choices are [animal.selectUnique(3, or).pluralForm]. In the meantime, I am playing Catan with my best friend [name], and I have just rolled a die, and the values are [6Die.selectMany(2)].

Result

I am considering getting a pet, and my top choices are cats, dogs or turtles. In the meantime, I am playing Catan with my best friend Ian, and I have just rolled a die, and the values are 5 and 5.

As shown above it's "dogs or turtles" and "5 and 5"

Variables

Sometimes, you want to reuse the value generated, this can be done using variables.

I had a pet [pet=animal.selectOne] and it is the best [pet] in the world.

Result

I have a pet cat and it is the best cat in the world

Consumable list

Sometimes, you want to use items in a list all over your document and you don't want to repeat the item, this is where "consumable list" comes in. As the name suggest, each time you generate one or more item, you are consuming that item, and as the saying goes, "You can't eat your cake and have it". This means the selected item is removed

list: products
  egg
  rice
  milk
  bread

s = products.consumableList
---

Grocery list

1. [s]
2. [s.selectUnique(2)]
3. [s.selectOne]
4. [s.selectOne]
5. [s.selectOne]

Result
Grocery list

rice
milk and bread
egg



As you can see, there are four items in the list because the size of the list is 4, so the 5th item cannot be generated

Sentences

You can break a large block of text that can be reused.

sentence: bio
  Call me [name]

---
[bio]

Result

Call me Ishmael

Nested list

You can nest a list inside a list

list: country
  Nigeria
    name = Nigeria
    continent = Africa
		height = {7-18}
    city
      Ibadan
      Lagos
      Abuja
  USA
    name = United State
    continent = North America
		height = {7-19}
    city
      New york
      Los Angeles
      Texas
---
I was born in [c=country.selectOne, c.city.selectOne], [c.name] in the continent of [c.continent]. That was {18-35} years ago, standing at [c.height, '0', 'cm'], I am hopeful for the future.

Result

I was born in Ibadan, Nigeria in the continent of Africa. That was 21 years ago, standing at 175cm, I am hopeful for the future.

As you can see, there are two statements in the square brackets. You can add as many statements as possible inside the squared brackets, and they are all processed

The app version is [{'v', 0-9}, {0,9}, '.', {0,9}, '.', {0,9}, '@', {use:semver}]

Result

The app version is v25.5.8@beta

As you can see, the code returns anything in quotation as it is.

You can even import a list directly inside the list

list: living_things
  {use:animal}
  {use:plant}
  {use:fungi}
  {use:bacteria}

Assuming animals contains subdivision like mammals, reptile, insect

animal_list = {use:living_things.animal}

sentence: mammal
  Today, we will be discussing mammals, for example [animal_list.mammal].

{use:mammal}

Result

  Today, we will be discussing mammals, for example dog.

Conditions

List can be boring, or even limiting, but we could build on these simple data to create a more complex data sets

Using "or"

You have seen the "|" in action, for choosing between two options, but it can also be used to provide a default value. For example

Username: [u=user.selectOne, u.username|'N/A']

Result

Username: big_boy

In this example above, the user select has a username called "big_boy". What if the username is not defined? it will return "N/A"

Result

Username: N/A

Switch

This is a conditional list that returns data based on the value

list: animal
  mammal
  reptile
  amphibian
  aves

sentence: mammal_sentence
  they are vertebrate animal whose young are nourished with milk from special mammary glands of the mother.
sentence: reptile_sentence
  they are cold-blooded vertebrates that lay eggs
sentence: aves_sentence
  they are a group of warm-blooded vertebrates characterised by feathers, toothless beaked jaws, the laying of hard-shelled eggs
sentence: amphibian_sentence
  they are cold-blooded vertebrates (vertebrates have backbones) that don't have scales.

switch: info
  mammal_sentence = [s_var=mammal]
  reptile_sentence = [s_var=reptile]
  amphibian_sentence = [s_var=amphibian]
  aves_sentence = [s_var=aves]
  'No group was selected'
---
[s_var = animal.selectOne, s, ':", info]

Result

Aves are a group of warm-blooded vertebrates characterised by feathers, toothless beaked jaws, the laying of hard-shelled eggs

info

When using view, the "case" refers to what is used to compare, e.g. in the info switch, the case is s_var. If you want to use info, you must declare s_var. You can also provide an optional default value that is returned in case s_var wasn't provided

[info]

Result

No group was selected

You can also use basic greater than or less than as well

score = {0-100}
switch: grade
  Excellent = [score > 80]
  'Very good' = [score > 70]
  Good = [score > 60]
  Pass = [score > 50]
  'Fail'

---
With a score of [score], that's [grade.sentenceCase]

Result

With a score of 75, that's very good

This can be used to handle nested list

list: country
  Nigeria
  Ghana

country_name = [country]

list: nigerian_name
  male
    Timilehin
    Enitan
  female
    Omotayo
    Yetunde
    Teniayo

list: ghanian_name
  male
    Kwasi
    Kwado
    Kwabena
  female
    Yvonne
    Sylvia

switch: name_list
  [nigerian_name] = [country_name=Nigeria]
  [ghanian_name] = [country_name=Ghana]

gender = {male|female}

switch: name
  [name_list.male] = [gender=male]
  [name_list.female] = [gender=female]

---
What's your name?
My name is [name]

Result

What's your name?
My name is Timilehin

Repeat

This allows user to write repetitive stuff once

repeat: text_list, n=5
  'I love this'

---

[text_list]

Result
I love this
I love this
I love this
I love this
I love this

As you probably noticed the n=5, this doesn't just tell you the number of result to return, but can be used to track the count.

list = products.consumableList

repeat: shopping_list, i=5
  [i, ". ", list.selectOne]

---
[shopping_list]

Once again, we only have 4 products!

Result

rice
milk
egg
bread


AI will be implemented progressively

AI

This allows you to use AI directly in the app

Text

{use:prompt('generate a story about a brave boy')}

This is like a simple prompt

Result

Once upon a time, in a land far far away...

Inline vs External

Inline

Generators can be parsed directly inside a template, so you we can write it inside it, and separate it using ---. The generators should always come first.

list: generate_example
  value_1
  value_2
  value_3

---

Template content: [generator_example]

Anything above the --- is hidden, but anything in it should also be a generator or variable declaration. Anything else will be ignored

This is a generator for some rainbow colours

list: rainbow
  red
  orange
  yellow
  green
  blue
  indigo
  violet

It should be noted that rainbow colours are continuous and this list is arbitrary

---

The colour is [rainbow]

Result

The colour is yellow

But the challenge is that this can get unwieldy pretty quickly. Hence, come external generators.

External

Generators

First create the generator

rainbow.generator
list
  red
  orange
  yellow
  green
  blue
  indigo
  violet

Now you can use in two ways, square brackets or curly brackets

filename.template
color = {use:rainbow}
---

Color: {use:rainbow}
Color: [color]

Result

Color: red
Color: green

Note, you can also assign the generator to its own name

filename.template
rainbow = {use:rainbow}
---

Color: [rainbow]

Result


Color: orange

Introduction​

Creating data​

Generating values​

Lists​

Grammar​

Ranges​

External data​

Creating generators​

Transform​

Cases​

Sex​

Tense​

Functions​

Variables​

Consumable list​

Sentences​

Nested list​

Conditions​

Using "or"​

Switch​

Repeat​

AI​

Text​

Inline vs External​

Inline​

External​

Introduction

Creating data

Generating values

Lists

Grammar

Ranges

External data

Creating generators

Transform

Cases

Sex

Tense

Functions

Variables

Consumable list

Sentences

Nested list

Conditions

Using "or"

Switch

Repeat

AI

Text

Inline vs External

Inline

External