Chapter 5. Adding new foods and editing the nutrients or units of existing foods
Prev |  | Next

## Chapter 5. Adding new foods and editing the nutrients or units of existing foods

The `master` file comes with over 7,000 foods. However, you might find that you also need to add additional foods to Pantry. This chapter will tell you how to add additional foods by creating an XML file.

If you have a prepackaged food that already has a nutrition label, you can easily add it to a file. If however you have multiple foods that you wish to combine, then what you want is a recipe. We will discuss recipes in the next chapter.

As you may recall from our earlier discussions, an essential element of Pantry is the food. Foods are contained in food files. There are several different kinds of food files. Until now, all the food files we have used have been Pantry native files. You have been able to copy foods from one Pantry native file, such as the `master` file, and change the traits of those foods. To create entirely new foods, you will create a different type of food file, which we will call a Pantry XML file. Unlike a Pantry native file, the Pantry XML file is in human-readable, plain-text XML, which allows you to create new foods.

This chapter will lead you through how to create your own foods, step by step. If you're the impatient sort who would rather learn by seeing some examples, consult the `examples` directory in the Pantry distribution.

## 5.1. Creating a new food

### 5.1.1. Create a new blank XML file

In your favorite text editor, create a new file whose name ends with `.xml`. As an example, we will create a file named `foods.xml`.

The root element of a Pantry XML file is a `pantry` element, so to get started create that element.

Example 5.1. `foods.xml` file with blank `pantry` element

    <pantry>
    </pantry>

### 5.1.2. Create a `food` element

Each food you create in the `foods.xml` file is contained within a `food` element. The `food` element has several attributes. Each corresponds to the various food traits that we've discussed earlier: `name`, `group`, `date`, `meal`, `unit`, `qty`, and `comment`, `refDesc`, and `pctRefuse`. Only the `unit` and `qty` attributes are required. The `unit` attribute may contain `g`, `oz`, or `lb`, or it may contain one of the units given in the `units` element, which we will discuss shortly. The `qty` and `pctRefuse` attributes may contain a number, a fraction, or a mixed number.

Attributes other than `qty` and `unit` are optional. If you don't have any values for them, just leave the attributes out altogether. Typically you will set the `name` and `group` to something useful while leaving many of the others out. If you set the `pctRefuse` trait, remember that you are setting percentages--that is, to indicate that your food is 15 percent refuse, set this attribute equal to `"15"`.

Typically you will be getting your nutrition information from food labels. Usually these will indicate a serving size, as well as a serving in grams. You will set the `unit` and `qty` traits to match what is given on the food label. As an example, we will use a Clif Bar. You may find it helpful to follow along with its nutrition label, which you can find here.[12] Its label shows a serving size of 1 bar. So, we enter the following text into our `foods.xml` to start:

Example 5.2. `foods.xml` with `food` element

    <pantry>
        <food name="Clif Bar, Oatmeal Raisin Walnut" group="Snacks" unit="bar" qty="1">
        </food>
    </pantry>

### 5.1.3. Create `nutrients` elements

Next, you will create nutrients for your food. You define each nutrient by creating a `nutrient` element. Each `nutrient` element has three required attributes.

The `name` attribute to the `nutrient` element gives the name of the nutrient, such as `Calories` or `Iron`. These names must correspond to one of the nutrients that is allowed in Pantry; to get a list of the allowed nutrients, run `pantry --nutrient-list all --print list`. The names are case sensitive, so although `Saturated Fat` is a valid nutrient, `Saturated fat` is not a valid nutrient.

The `amount` attribute to the `nutrient` element is a number indicating the amount of the corresponding nutrient. This can be an integer, floating-point number, a fraction, or a mixed number.

The third attribute to the `nutrient` element is `units`. Set this equal to the units for the nutrient--e.g. `g` or `mg`. For calories, use `kcal`. The value for `units` must match the units given for the nutrient in the table you see when you run `pantry --print list --nutrient-list all`.

For some nutrients, you may set the `units` attribute to `%`. Setting this attribute to `%` indicates that the `amount` attribute is a percentage of an FDA Daily Value. Pantry will convert the `amount` attribute to an appropriate amount. This is useful because vitamins and minerals are listed on food labels by percent of daily value, rather than by amount. You may only use `%` for nutrients for which there is a Daily Value. To get a list of all nutrients that have a Daily Value, run `pantry --print list --nutrient-list dv`.

To continue with our Clif Bar example, here is the Clif Bar with its nutrient information. Because I am lazy, I did not enter all the nutrition information; instead, I just entered all the macronutrients and four of the vitamins and minerals.

Example 5.3. Food with `nutrients` element

    <pantry>
        <food name="Clif Bar, Oatmeal Raisin Walnut" group="Snacks" unit="bar" qty="1">
            <nutrient name="Calories" units="kcal" amount="240"/>
            <nutrient name="Total Fat" units="g" amount="5"/>
            <nutrient name="Saturated Fat" units="g" amount="1"/>
            <nutrient name="Trans Fat" units="g" amount="0"/>
            <nutrient name="Cholesterol" units="mg" amount="0"/>
            <nutrient name="Sodium" units="mg" amount="130"/>
            <nutrient name="Potassium" units="mg" amount="310" />
            <nutrient name="Total Carbohydrate" units="g" amount="43"/>
            <nutrient name="Dietary Fiber" units="g" amount="5"/>
            <nutrient name="Sugars" units="g" amount="20"/>
            <nutrient name="Protein" units="g" amount="10"/>
            <nutrient name="Vitamin A" units="%" amount="30"/>
            <nutrient name="Vitamin C" units="%" amount="100"/>
            <nutrient name="Calcium" units="%" amount="25"/>
            <nutrient name="Iron" units="%" amount="25"/>
        </food>
    </pantry>

### 5.1.4. Creating `unit` elements

Finally, it is time to enter units for the food, which you do using the `unit` element. These elements map common units of measure to a food's weight in grams, and they correspond to to the available units that we discussed earlier. Thus, each `unit` element has two attributes. `name` corresponds to the name of the unit, such as `cup` or `stick` or `box`--whatever is appropriate. The `grams` attribute corresponds to whatever the weight of a single `name` is, in grams.

As always, Pantry will provide the units `g`, `oz`, and `lb` for you, so do not enter those in `unit` elements. However, if you entered anything other than `g`, `oz`, or `lb` for the `unit` attribute of the `food` element, you must define a corresponding `unit` element. Thus, because the `unit` attribute for our Clif Bar is `bar`, we must define a corresponding `unit` element. With that, we have a complete `food` element.

Example 5.4. Complete `foods.xml` file.

    <pantry>
        <food name="Clif Bar, Oatmeal Raisin Walnut" group="Snacks" unit="bar" qty="1">
            <nutrient name="Calories" units="kcal" amount="240"/>
            <nutrient name="Total Fat" units="g" amount="5"/>
            <nutrient name="Saturated Fat" units="g" amount="1"/>
            <nutrient name="Trans Fat" units="g" amount="0"/>
            <nutrient name="Cholesterol" units="mg" amount="0"/>
            <nutrient name="Sodium" units="mg" amount="130"/>
            <nutrient name="Potassium" units="mg" amount="310" />
            <nutrient name="Total Carbohydrate" units="g" amount="43"/>
            <nutrient name="Dietary Fiber" units="g" amount="5"/>
            <nutrient name="Sugars" units="g" amount="20"/>
            <nutrient name="Protein" units="g" amount="10"/>
            <nutrient name="Vitamin A" units="%" amount="30"/>
            <nutrient name="Vitamin C" units="%" amount="100"/>
            <nutrient name="Calcium" units="%" amount="25"/>
            <nutrient name="Iron" units="%" amount="25"/>
            <unit name="bar" grams="68"/>
        </food>
    </pantry>

[12] Use of the Clif Bar in this example wholeheartedly implies my endorsement of Clif Bars. They are handy, tasty snacks.

Prev |  | Next
4.7. Multilingual Pantry | Home | 5.2. Using a Pantry XML file