Hierarchical Lists

## Introduction

Perchance allows you to create "lists of lists" by indenting your items appropriately. This may seem unusual at first, but as you explore Perchance's more advanced features you'll see that it can sometimes be useful.

## Examples

### Creating a Multi-level List

Here's an example of a multi-level list called "animal":

```
animal
    mammal
        kangaroo
        pig
        human
    reptile
        lizard
        crocodile
        turtle
    insect
        spider
        beetle
        ant

```

The result of `[animal]` will be "mammal", "reptile" or "insect" with equal likelihood (since we haven't added any likelihood indicators on those items). The result of `[animal.mammal]` will be either "kangaroo", "pig" or "human", with equal likelihood.

### `selectOne` in Multi-level List

What do you think `[animal.selectOne]` will result in? Remember that `animal` is a list ... *of lists* - so when we `selectOne` item from `animal` we get a random *list*. So when we write `[animal.selectOne]`, it'll essentially give us either `[animal.mammal]`, `[animal.reptile]` or `[animal.insect]`, all with equal probability.

Thus, both these lines are equivalent:

```
[animal.selectOne]
{[animal.mammal]|[animal.reptile]|[animal.insect]}

```

That can be a bit confusing since it may initially seem like `[animal.selectOne]` would simply result in "mammal" or "reptile" or "insect" - but that's not the case, since those items are themselves *lists*, and so `selectOne` gives us *the whole sublist*, which then resolves to a single item from that sublist.

So the result of `[animal.selectOne]` would be either *kangaroo, pig, human, lizard, crocodile, turtle, spider, beetle, or ant* - all with equal likelihood, since we haven't altered the odds of the sublists and they all have the have the same number of items.

Perchance allows you to nest items to an arbitrary depth. You could, for example, have a nested list which has many levels: `[planet.country.town.house.room]`.

### "Object" List

You can also use hierarchical lists for stuff like this:

```
 race
 	dwarf
 		height = {7-15}0cm
 		name = Dwarf
 		type
 			Mountain Dwarf
 			Aleithian Dwarf
 	elf
 		height = {12-20}0cm
 		name = Elf
 		type
 			High Elf
 			Night Elf
 	...

 output
   Yes, a [r = race.selectOne, r.name] of that description passed through here several months ago. {A} [r.type] if I recall correctly. About
[r.height] tall.

```

And if for some reason we specifically wanted a random dwarf height then we could write `[race.dwarf.height]`.

If you're a bit confused by all this hierarchical stuff, don't worry about it - for the vast majority of generators top-level lists will be completely fine. It's only if you're building somewhat complicated generators that nesting will start to become useful to help organize and compartmentalize our code.

## Detailed Example

### Example List

Say you wanted to generate a random character of a certain fantasy race (elf, orc, human, etc.). Each of these different races have different probabilities of having different characteristics. For example, perhaps elves have a greater chance of having green eyes than the other races. And perhaps orcs can have red eyes, whereas the other races can't. So how do we create a random character while being able to control the probabilities of their characteristics based on their race?

There are multiple ways of doing this, but one way is to use "hierarchical lists": lists of lists of lists, as many levels deep as we desire. Have a look at this generator and try to get a rough sense of what's happening.

Assuming you've done that, let's break it down by first looking at the `race` list (the only list other than `output` in this generator):

```
race
	elf
		name = elvish
		eyeColor
			green
			emerald
 	human
		name = human
		eyeColor
			blue
			brown
	...

```

You can see it has 3 items: `elf`, `human` and `orc`. Only the first two are shown here for brevity. Each of these items are themselves a list containing `name` and `eyeColor`. And finally, `eyeColor` is a list containing the possible eye colors for that race.

So what would happen if we evaluated `[race]`? It'd just print out "elf", "human" or "orc", each with 33% probability. You can test that out by typing "[race]" into the bottom-left panel in the editor.

### Storing and Accessing Properties

But how would we create a sentence like "She was an orcish warrior with red eyes."? We'd need to write something like `She was a [race] warrior with ??? eyes.`, but as indicated by the question marks, how do we know which race was selected? We need to somehow *store* our previously selected race and then use it to randomly select a valid eye colour for that race.

Here's a generator that shows how we store something so that we can use it again later , and here's another that shows us how to grab properties of the remembered item (**or refer to the** **Storing Text**). In the first example you can see this line:

```
I can never remember what [w = word.selectOne] means. Do you know what [w] means?

```

Put simply, we're selecting one item from the `word` list and putting it in a new variable called `w`. Fun fact: When you write `[word]`, the perchance engine assumes that you wanted to select one item from the `word` list and print it out. However, when assigning a specific item to our new `w` variable, we need to explicitly tell perchance that we want `w` to be a single item from the `word` list. If we just wrote `[w = word]`, then we'd be assigning the *whole* `word` list to `w`, and so `w` would just become an alias (another name) for `word`.

This "aliasing" or "nicknaming" can come in handy to shorten long list names:

```
[b = universe.middleEarth.shire.bilbo] ... [b.hitPoints] ... [b.mood]

```

The final thing left unexplained is the fact that we can put multiple commands within a square-bracket block. We separate them with a comma like so: `[b.hitPoints += 10, b.name]`. Here we've added 10 hitpoints to bilbo, and then called the `name` subproperty of bilbo. Perchance only displays the last item in a list of commands. This is handy when you've got commands that you want to execute, but you don't want them to print out anything.

In that last example we increased bilbo's hit points by 10 and then printed out his name. What if you don't want to print anything out at all? In that case you can do this: `[b.hitPoints += 10, ""]`. Notice that the second command is just a pair of quotation marks with nothing between them. That's equivalent to saying "print nothing". If there was something between the quotation marks, it would print that.

Here's another example generator that uses a hierarchy in a similar manner to the original example in this section.

If you'd like to learn more about hierarchical stuff, check out the advanced tutorial and examples Perchance pages, and List Quadrant.