How to use teapot like a pro

I like to make a big deal out of console applications that really are applications — that actually have a workable “GUI” beyond just a command and a few switches. It’s part of my quest in life: To dispel the irrational repulsion many people brag (yes, brag) about when they discuss using the console with Linux. 🙄

It’s been a while since I really walked neatly through a program though, and I feel I should do that with teapot. teapot is a very useful, very lightweight spreadsheet that I like a lot. I don’t need it very often though, and so each time I pick it up I have to relearn it again.

But on top of that, I have mentioned Oleo in the past, which is a very good console spreadsheet. But it’s not the only one out there, isn’t really to my liking, and there are things about teapot that are worth looking at.

The first trick might be getting it installed, since it isn’t in every distro — Ubuntu, for example, draws a blank if you ask the package search pages about it. AUR has it, with the caveat that it’s for “mathy” people, which I don’t dispute. It’s a spreadsheet, so you can expect to see some numbers. I know some people for whom that would be enough to be called “mathy.” 😉

If you decide to build it from scratch, you can take comfort in the thought that teapot only needs ncurses to get going. So I’m guessing with 99 percent certainty that (a), you can build it without too much hassle, and (b), it’s as light as a feather when in action. And that last part is a fact confirmed by htop.

Getting started is easy enough. Enter teapot at the prompt, and you should get something that looks like this.

Fair enough, it looks like a spreadsheet. We were expecting that much.

Except … hold on: The columns aren’t labeled with letters. We have numbers across and numbers down. That’s a little unusual.

Yes, that alone is probably enough to either intrigue you or dismay you — teapot breaks convention by using numbers in both directions. Now the un-“mathy” people in the crowd are probably already considering panicking, but the “mathy” ones might suddenly be interested.

Because it means that there is an x-y coordinate for each cell — and in fact, most of teapot’s instructions and formulas rely on that to work. And best of all for the “mathy” types, there is an unseen z dimension at work here, so the layers beneath this page are also addressable.

You know, maybe that “mathy” label was right.

No matter. Let’s get started. I’m going to make a spreadsheet for this example that shows how much of my lowly paycheck went into my X60s, in the form of memory and a new hard drive. First, I’m going to put the make and model of my hard drive in the upper left block. Type “SATA3G hard drive”, starting and finishing with quotes.

 

My god, it’s full of stars. … Well, we’ve already run into our first problem. It seems that the title is too long for the width of the cell. teapot tells us that by showing those stars, and signaling to us that we should probably widen that column a little.

No problem. Press F10.

teapot has a menu system — I wasn’t kidding when I mentioned GUIs in console programs. Select W)idth, and set the column width to 24.

That’s better. You can see in the bottom line there that the coordinates for the cell — 0,0,0 — contain the quote-enclosed text we entered. Now a little navigation: Use the cursor keys to skip through the spreadsheet, and move down a row. Then enter the next item, “PC2-5300 memory”.

If you make a mistake after you enter data, just press return on that cell again to edit it. If you make a mistake and need to back out of the menu, press CTRL+c.

I bought two sticks of memory in different sizes, so it would be nice to just copy that text into the row below. teapot uses block marking, a lot like old-style pre-graphical word processors. You mark a block and then tell teapot what you want done with it.

In this case, press the period (“dot” or .) key twice. This marks the cell as the first corner of the block and the last corner of the block. If you move the selection highlight after that, you can see that the block (or cell, in this case) remains lit.

Now that we have a selection, we can tell teapot to copy it to a new location. Put the selector on the row beneath the memory text, and press F10. Choose B)lock, then C)opy, and confirm it.

That did the trick. One small problem though: We still have the original cell marked. How do we un-mark it? Press period (“dot” or .) again, and it will disappear.

Next, add the text for the last thing on the list, the “SATA enclosure”. At this point, the spreadsheet should look like this.

The problem at this point is that I forgot a header row. It’s not really necessary, but as long as I am going to make this, I might as well make it clear what I am talking about. Let’s insert a row above the whole business.

Navigate back to the top of the page, or just press the less-than key (<). Press F10, then B)lock, I)nsert, R)ow, and then W)hole line.

We used the block menu even though we didn’t have a block defined, and it worked fine this time. And notice that after you’ve inserted the row, you’re still in the menu dialog; press CTRL+c to leave that. I’ll add some headers to this table.

I like a quantity, cost each and total cost for each line. Nothing fancy, just the kind of things you’d expect on an invoice or an order form.

For the quantity column, I can enter 1 for each, since I only bought one each. For the currency I can use the cost in yen for each one, so the table ends up looking something like this.

And I see I made one mistake again: I bought memory of two different sizes but didn’t leave a column for the size. I can insert a column for “Gb” quickly, and add the information where it’s appropriate.

Of course, those headers are skewed off to the left while their information is on the right. Let’s align the headers to the right so they look nice. Mark a block with only the numeric headers highlighted: Press period at the “Gb” column, then skip to the right with the cursor keys until the “Total cost” column is highlighted as well, and then press period again.

If you move away from the marked block, you can see that the entire area is now inverted. Press F10, then A)ttributes, R)epresentation, and R)ight.

So long as you have a block marked, the attributes and representations will be applied to the block. Press CTRL+c to leave the menu dialog, then press period again to unselect the marked block.

Let’s get some totals in here. Obviously, the quantity times the cost will give me the total cost for each line. teapot is flexible enough that there are several different ways to do that, but to avoid being too “mathy,” I’ll take the easiest way.

Go to the first item in the list, to the total cost cell, and we’ll give it a formula to calculate. Enter @(2,1,0)*@(3,1,0) in that box, and the total is shown for that line.

One small problem though, created mostly because human beings are innately lazy: I’d rather not retype that three times over. I can fill the contents of that cell through the cells below it, but then the formula always points back to that first row of numbers.

So instead of specifying the exact x-y-z location for the formula, I’m just going to give it the x location. If teapot doesn’t find a y or z in the location of the cell, it takes the one where it is at the moment. So instead of the multiplication operation above, edit the cell to show @(3)*@(2) — the x locations only of the data I want to multiply.

Then mark the block for that one cell, move down one cell and use F10, B)lock, F)ill. For the number of column-wise repetitions say 1 — the column we’re in. For row-wise, say 3 — the current cell plus the two below it. For depth-wise say 1 — the layer we’re in.

And voila.

Adjusting the quantity or the price will change the values across the sheet, like all good spreadsheets should.

Just for fun, let’s sort a few columns. Select all of the data rows (but not the grand total), and then hit F10, B)lock, S)ort, R)ow. For the “X position of key vector,” and “Z position of key vector,” enter 0. The A)scending and S)ort region.

We sorted the list alphabetically, by the name of the item (X key vector 0) over one level of “sheets” (Z key vector 0). This could be useful if you need to keep day-to-day spreadsheets of the same information, since it means you can sort vertically over a “date” cell.

Changing it back is simply reversing the same process, but using the X key vector for the “Cost each” column — 3. And don’t forget to use “descending.” 🙂

There’s one more thing that teapot will do that is worth looking at, because it changes how you can use the entire spreadsheet — or the entire idea behind a spreadsheet, really. Try this: Go to the top of the total cost column, press F10 then A)ttributes then L)abel. Now call this “first”.

The status line near the bottom changed, with the label included. Now go to the last in that column, and give that the label “last”.

Now skip down one more line and enter this for the grand total of that column: sum(first,last).

“Okay, great,” you say. “It knows how to sum things, and it can use those labels to do it. So what?”

Well the “so what” part is principle, not action this time. It essentially means you can label, refer to and connect from any cell over the three dimensions of the spreadsheet, and not need coordinates to do it.

You can skew a column of numbers, sum them over a series of cells, insert wide gaping holes in pages, but the labels are what determines how numbers are calculated. teapot takes its labels seriously and allows you to do some cool things with them, and the results are about what you need.

It also means that those text labels we put on the left, or the column headers on the right are completely superfluous now. They’re only there for uninitiated humans to find there way around the page. We could just as easily label cells as “quantity1”, “quantity2” and so forth. Then call the cost cells “cost1”, “cost2” and so on, and just sum the opposite corners of a range.

It’s not a mind-blowing or life-altering idea, but it does mean that formulas and number-crunching become easier to think about, and don’t require you to second-guess because a cell shifted to allow for more data. So long as the labels stay the same, the calculations work the same.

The next obvious question is, “Where can I go with my spreadsheet?” To which, I can say that teapot saves in XDR natively for mathematical precision, and exports to at least four or maybe five others. I see that two of those — CSV and HTML — are something Google documents can open, albeit as word processor pages.

Beyond that, I am not up-to-snuff on what is the file format du jour for spreadsheet programs. I am guessing a modern one can probably handle something teapot exports to.

teapot does a lot of other things; the list of formulas available to you, and the way you can access cells or run counts is very impressive. The source package includes a teapot-driven variation on Conway’s game of life too, so it’s not all serious stuff.

Of course there are quite a lot of things teapot doesn’t do, like export in Excel format or draw exploding pie charts in three dimensions and 64,000 colors. For things like that you will probably want to investigate, bigger, bulkier and slower spreadsheets, built by other people.

But if you want something that will run in a slice of memory thinner than a piece of paper, this is a good choice. It’s fast, light, sensible and flexible and comes with a very good documentation file (check the source package for the doc folder). And while there’s a degree of “mathy-ness” that you can’t get away from, it’s certainly nothing to be afraid of. 😉