gram: luck

> ./sample-data-old/welcome.txt

Lenses
(coming soon!)

_Welcome to Potluck!
Potluck is an environment for making *personal software* out of text documents.
 https://www.youtube.com/watch?v=jNQXAC9IVRw

It's like a regular notes app, but you can add *live searches* which detect patterns in your text as you type: dates, times, quantities, food ingredients, anything you like. You can then write little Javascript formulas to run computations and show the results back in the text doc.

Just with these simple concepts, you can build many kinds of software:

- 🥘 **Recipe app**: scale up ingredients and show a timer in the directions
- 💪 **Workout tracker**: A simple text-based workout log with a calendar view
- ✅ **Todo list**: write a todo list with time tracking and convenient formatting
- ✈️ **Trip plan**: make a trip plan that shows open times + flight statuses
- 🌸 **Plant watering**: conveniently keep track of when to water your plants
- 🍞 **Bake Sale**: Keep track of sales and prices at a cash register
- 💵 **Stock Portfolio** tracker with live stock prices

All of these examples are pre-loaded in the left sidebar, feel free to poke around.

## Getting started

To learn the ropes, let's build a banana counter doc.

When we type something like "7 bananas" anywhere in the doc, it will show a row of banana emojis next to the text, corresponding to the number of bananas. Fun!

**Making a live search**

To start, hit **Cmd-Shift-F / Ctrl-Shift-F** (or click the magnifying glass in upper right) to open the search panel. Type the text below into the searchbox, then hit Enter.

```
{number} bananas
```

You just created your first live search! It matches any number, followed by the word "bananas".

*See it update*: Try typing "10 bananas" somewhere in the doc. You'll see the search update.

*Rename the search*: The search has a name "search1" by default.  Rename it from "search1" to "numBananas" (you can directly just edit the name) so we can easily reference it later on.

*Advanced tips*
- Inside the { ... }, you can put the name of any existing search in Potluck. That includes your own 
- {number} is a built in pattern in Potluck, which is why you can search for it. There are lots of other built in patterns you can include inside curly braces. The autocomplete in the search box gives you a full list.
- You can even write a regular expression if you know how, by writing something like this inside curly braces: {/[a-z]+/}

**Doing a computation**

Next let's add some emojis.

First, let's add a **capture group** to our search to extract just the number from the pattern. Edit the search to be like this:

```
{number:num} bananas
```

Next, click the "+" button on the right side of the table. In the formula box, type in:

```
Repeat("🍌", num)
```

Now you have strings of emojis in your table!

*Advanced tips*
- You can rename the column using the settings box
- If you know Javascript, you can type any JS into the formula box. It's just evaluating a JS expression.
- There are a bunch of helpful functions like Repeat built into the system. You can see a reference with the ? button in the formula bar.

**Showing the computation in the text**

The emojis are only in the table. Let's show them in the doc too!

Click the settings icon next to col2, and for "Display in document", select "Next to text".

You should now see emojis next to this text: 3 bananas

*Advanced tips*
- Try out the other "display in document" settings like replacing the text.
- There's a special option for styling the text. To use this, you need to name the column as a CSS property, and return a CSS value as the formula result. Check out the built-in Markdown search on this doc for some examples.

**Querying across searches**

Final step: let's tabulate the total number of bananas in this whole doc so we know how many we've been eating!

We'll display the total right here with a label:

Total bananas:

First, make a new search, which finds the label text above ("Total bananas:"). This search might seem a little weird but the point is just to find the label in the doc so we can tell the system where to put the total number.

Next, make a new column in that table and add this formula:

```
Sum(FindAll("numBananas").map(row => row.data.num))
```

(If the formula doesn't work, it might be because you didn't rename your original search from "search1" to "numBananas" in the previous step)

Then change the display setting to show the sum next to the label. You now have a banana total! If you add more bananas in the doc they'll show up in the total.

OK hold on, how does this formula work?
- FindAll takes the name of a search and returns all the rows in the table
- Each row has a .data property which includes all the columns in the row
- We extract the `num` column from each row in the numBananas table, and then sum them with the Sum formula

## Next steps

To explore further:

- try looking through the various documents in the sidebar and see what they do and how they're implemented
- try making your own documents and playing around!
- ask us for help if you have questions

A few more tips:

- By default this is just a playground app, and it doesn't save data. You can sync the web app with a directory on your local filesystem if you want to save files. Hit the "refresh" icon in the top right to start syncing with your filesystem.
- There's a question mark icon in the formula editor for a column which shows all the formulas available in the system