The Basics

## Introduction

Perchance is a website that allows its users to create a "Random Text Generator". Perchance is based on HTML/CSS, and JavaScript, and the secret mission of the creator of Perchance is to get people interested in coding with a smooth, fun learning-curve .

Perchance's structure is based on other awesome random text languages like randomgen by Orteil and Rant by TheBerkin. Many thanks to these and other DSL creators which inspired Perchance's syntax and functionality. You might also like to check out Chartopia - another website which allows you to make random generators.

## How to Use

### Simple Example

Perchance is all about lists. You simply create lists of different things and then reference the lists from one another. For example, we could create a list of animals, and a list of sentences, and then use the animals list *within* the sentences list like so:

```
animal
   pig
   cow
   zebra

sentence
	That [animal] is very sneaky.
	I befriended a wild [animal] yesterday.

```

Pretty easy, right? In each sentence, `[animal]` gets replaced by a random item from the animal list. As you can see, list items are indented from the list name. You must use **one tab** or **two spaces** to indent your list items.

### Spaces

If you want to put a space before or after an item, you need to use a special character pair, `\s`, at the start and/or end of your item. For example:

```
my_list
	\s    this item has some space on either side    \s
	\s  this one just has some space at the start
	this one just has some space on the end         \s

```

When the engine outputs this text, the `\s` bits will be replaced with a space. If you wanted an item called "My Item Text" with just one space on either side you would write `\sMy Item Text\s`. The reason we need to use `\s` for spaces on either side of items is because Perchance "takes indentation seriously". If you put spaces at the start of your item, Perchance will think you're trying to indent the item further. As you'll learn soon, Perchance allows you to use multiple levels/tiers of indentation (you can create a hierarchy of lists within lists), which means we need strict indentation rules. Regarding normal spaces at the *end* of items, Perchance will trim them off (ignore them) during initialization.

### Special Characters

If you'd like to put a "tab" character in your items, you can use `\t`. As you can see, backslash is a special character in Perchance. If you want to use an *actual* backslash, then you need to write a double backslash like this: `\\`. Similarly, if you want to use a literal square bracket, curly bracket or equals sign, then you need to put a backslash before them like this: `\[` , \{and this: `\=`. That way the Perchance engine will just treat it like a normal text character. The backslash is a magical character that you'll use quite often in your random-generator-building career.

## Example

Firstly, you want to open up this page (the minimal generator that most people use to make their generators) or another template and take a look at the code.

You'll want to get pretty familiar with the `output` section of the code, because that's what you'll be editing. So, in the first image, I've made an example in which I replaced the `output` list with names of fruit.

Now when you press randomize, it will pick a random fruit. That's pretty simple. If you want to output a number, just use a curly bracket like so in the second image.

This will show you how to output numbers. That's also pretty simple. Or, if you want to output a number and a fruit name, you can use the third image to show you how to do so.

See how I've created a **new** list called fruit and used square brackets to reference the list into the output. If you want a more detailed tutorial, you can go to the perchance tutorial.

1. ↑ 1.0 1.1 Perchance Welcome Page: https://perchance.org/welcome
2. ↑ 2.0 2.1 2.2 Perchance Tutorial: https://perchance.org/tutorial