Chapter 2. Basic Pantry commands
Prev |  | Next

## Chapter 2. Basic Pantry commands

The core program of Pantry is named, appropriately enough, pantry. In this section you'll learn how pantry works. But first you'll need to understand the way Pantry was designed--that is, the Pantry Paradigm.

## 2.1. The Pantry Paradigm

The basic unit of Pantry is the food. Foods are grouped together and stored on your computer in files. There are four different kinds of files that store foods, but the most important kind is simply called a Pantry native file.[2] Pantry works very quickly with Pantry native files, even if the file contains thousands of foods.

Pantry comes with a Pantry native file named `master` that contains 7,519 foods. These foods come from the U.S. Department of Agriculture's National Nutrient Databse for Standard Reference, release 20. A big thank-you goes to these folks for producing this database--without it Pantry would never have been written.[3]

Every food has several traits. Later on you will learn how you can set a food's traits; foods in the `master` file already have their traits set. The traits are:

Food traits

`name`

  The name of this food, such as `Bananas, raw`.

`date`

  The date on which you ate this food. This is a string; no special date formatting rules apply to it.

`meal`

  The meal in which you ate this food (`Breakfast` `Lunch`, `midnight snack`, etc--whatever you wish)

`group`

  Useful for grouping foods together. You can use familiar food groups (such as `Dairy`, `Poultry`, etc.) or you might group foods together if you eat them together (for instance you might have a group "Cereal and Milk" in which you place those two foods.) We'll learn more about how you can use groups later.

  In the `master` file, each food's `group` trait is already set to one of twenty-four food groups, such as `Fruits and fruit juices` or `Snacks`.

`qty`

  How much of this food you ate. Pantry records this internally as a string; Pantry internally converts it to a number as necessary to perform calculations. You therefore set the `qty` trait to a string that will convert to an integer or to a floating-point number. This can be an integer, floating-point number, or a fraction, such as `1/3`. It can even be a mixed number, such as `1 1/3`. You can set `qty` equal to zero, but this does not delete the food--later we will discuss how to delete foods.

`unit`

  A description of the amount of this food you ate. The units that you can pick from vary for different foods. We will use the term available units to refer to the units that you can pick from for a particular food. Every food has at least three available units: `oz`, `g`, and `lb`. The other available units vary by food. For example, the food in the `master` file named `Bananas, raw` has several other units available, including `Cup, mashed`; `large (8" to 8-7/8" long)`, and `extra small (less than 6" long)`.

  When you keep track of which foods you eat, you'll set the quantity and unit to whatever makes sense: for instance, if you eat some `Bananas, raw`, you can set the quantity to `2` and the unit to `large (8" to 8-7/8" long)`. Remember, you can use any number for quantity you want, including floating point numbers, but you can set the unit only to what is available for that particular food.

`pctRefuse`

  The percent of this food that is waste. For example, with an apple, the core is refuse; for a chicken drumstick, the bone is refuse. Many foods have no refuse; in that case, this trait will be set equal to an empty string or to zero. As with the `qty` trait, Pantry internally keeps this as a string, converting it to a number as needed.

`refDesc`

  A description of the refuse, such as `Core` or `Bone`.

`comment`

  Whatever notes you may wish to add.

`order`

  Any string. As we will see later, pantry can sort reports however you like; using the `order` trait, you can sort foods into any arbitrary order.

All Pantry traits are strings. This includes the date trait. Thus, you can set the date trait for a food to `2007-05-06`, `05-06`, `Tuesday`, or even `Who cares?` if you wish. You may also set this trait, and all traits except `unit` and `qty`, to whatever string you wish. Only the `qty` and `unit` traits must be set to a non-zero-length value.

Pantry works by copying foods from one file to another. This makes the pantry command mostly a glorified copier. pantry starts by examining all the foods in each file that you specify. If you do not specify any `search options`, then all foods in the each file you specify are copied to a temporary place that we will call the buffer. Otherwise, if you specify any `search options`, then only the foods whose traits match all of the search options will be copied to the buffer. Any food not matching the `search options` you specify is ignored. pantry then modifies the traits of the foods in the buffer using any `change options` you specified. pantry can then send the buffer to a report (which prints the foods to standard output) and add the buffer to other files. All this is best understood with examples, as we will see in the next section.

[2] You'll notice if you run the Unix program file on a Pantry native file, it is most likely a Berkeley DB file. Unix geeks will cringe at the fact that this file is not plain text.

[3] Most food databases that you will find anywhere, such as the one at NutritionData.com, are derived from the same USDA database.

Prev |  | Next
1.3. About the documentation | Home | 2.2. Basic food searches