Storing Text

## Introduction

This section is about a fundamental feature of the Perchance engine. It may seem a little strange or confusing, but rest assured that it'll make more sense as we progress. Pay attention for this one! :)

## Examples

### Simple Storing

Let's start with a very simple example, as usual:

```
flower
    rose
    lily
    tulip

sentence
  Oh you've got me a [flower]! Thank you, I love [flower.pluralForm].

```

The problem with the above example is that *a different flower would likely be selected each time*. It'd output something like "Oh, you've got me a lily! Thank you, I love roses!". We'd like to use the same flower choice twice so that our sentence makes sense. Here's how we'd do that:

```
sentence
  Oh you've got me a [f = flower.selectOne]! Thank you, I love [f.pluralForm].

```

What we're doing here is selecting one item from `[flower]` (e.g. "tulip" or "rose" or "lily") and putting it inside "f" which is like a list with just one item. That's what the equals sign does inside square brackets - it allows you to "store things" under a unique identifier. We didn't need to specifically use the letter "f" as our identifier - we can use any name so long as it only has letters and numbers and doesn't start with a number.

Notice that we're putting `flower.selectOne` into the `f` identifier but we're also outputting the selected item **at the same time**. First the engine puts one item from `[flower]` into the `[f]` list, then it outputs that selected item into our sentence. In programming lingo we would generally call `f` a "variable" and we'd say that we "assigned" one item from the flower list to the `f` variable.

**Important note:**Imagine that the above `flower` list contained items like `{red|pink} rose` instead of just `rose`.

In that case you should write `[f = flower.selectOne.evaluateItem]`, or simply `[f = flower.evaluateItem]`, since `evaluateItem` automatically executes `selectOne` behind-the-scenes.

We need to use `evaluateItem` because we want to store something like `pink rose` in `f` rather than an "unevaluated" item like `{red|pink} rose`.

So, we make sure we "evaluate" all the random parts like `{red|pink}` before storing the selected item in `f`.
Here's another example:

```
name
  Addison
  Alex
  Alexis

lastName
	Smith
	Johnson
	Williams

sentence
  Her name was [n = name.selectOne]. [n.titleCase] [lastName.titleCase], if I recall correctly.

```

Remember, spaces are ignored inside square blocks. So `[ v = verb.selectOne ]` is the same as `[v=verb.selectOne]` and `[v]` is the same as `[ v ]`.

### Aliasing

You might be wondering why we can't simply write `[f=flower]`. This is because that would cause `f` to be a reference to the actual *list* called "flower", rather than to one randomly selected item of `[flower]`. Just remember, we want to store *an item* of the list, not the list itself. If you actually did write `[f=flower]`, then `[f]` would just be an alias (another name for) `[flower]`, and so `[f]` would return a new random flower each time (this may be a handy thing to know in case you want to shorten a list name that you're using lots).

```
flower
	rose
	lily
	tulip
output
   [f = flower] [f] // f is now the same as flower which can return "rose", "lily", and "tulip"

```

### Changing Stored Item

You can change the thing that's stored inside a variable by just assigning it a different value:

```
sentence
  I think her name was [n = name.selectOne.titleCase]? [n] [l = lastName.titleCase]? Wait, no, it was [n = name.selectOne]. Yeah, that's right, [n] [l].

```

**Caution:** Square brackets should not be used inside square brackets:

* This is **correct**: `[n = name.selectOne]`
* This is **incorrect**: `[n = [name].selectOne]`

Both are actually "legal" Perchance code, but the latter isn't doing what you intended, because square brackets have a **different meaning** when they're used *within* other square brackets. So for now, just remember: when you're inside square brackets, refer to list names directly - don't wrap them in square brackets.