Chapter 2. Basic Pantry commands

Table of Contents

2.1. The Pantry Paradigm
2.2. Basic food searches
2.3. Using the --print option
2.3.1. Combining reports
2.4. Details on searching
2.4.1. More traits you may use to search
2.4.2. Searches are regular expressions
2.4.3. My search is returning foods I don't want!
2.4.4. Searches are case sensitive
2.5. Changing food traits
2.6. Using nutrient lists to compare foods to particular nutrient goals
2.6.1. What are nutrient lists?
2.6.2. How nutrient lists are displayed in nuts reports
2.6.3. Using a different nutrient list
2.7. Using summary reports to see information about an entire buffer
2.7.1. Using the sum report
2.7.2. Using the groups report
2.8. Saving new foods with --add and --edit; deleting with the --delete option

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.