7.2. Creating a recipe
Prev | Chapter 7. Adding recipes | Next

## 7.2. Creating a recipe

Just like when you add new foods, you can write recipes in Pantry by using the Pantry XML file. While you enter foods in Pantry XML files by using the `foods` element, to enter recipes you use the `recipe` element.

### 7.2.1. Creating a recipes file and a `recipe` element

To create a Pantry XML file, start your favorite text editor and open a text file. For the purposes of our example we'll use `recipes.xml`, though you can create any filename that ends with `.xml`.

As we saw earlier when we created new foods, the root element of a Pantry XML file is `pantry`. Each recipe is contained in a `recipe` element. The `recipe` element thas the same attributes as the `food` element that we learned about earlier: `name`, `group`, `refuse`, `refDesc`, `date`, `meal`, `qty`, `comment`, and `unit`.

Of all these attributes, you are required to set only the `unit` and `qty` attributes. You can leave as many of the other ones out as you wish, though ordinarily you will set the `name` and `group` attributes while leaving many of the others blank.

Just like when you create a new food using the `food` element, you must set the `unit` attribute to one of the available units for the recipe. Pantry will automatically create the `g`, `oz`, and `lb` units for you. You can also have Pantry create a `serving` unit, as we will discuss shortly.

For our example, we will create a recipe with the name `Omari's Chili`. As you will see, the new recipe has its unit set to `serving`; shortly we will see exactly how this works. You will also notice that many of the attributes for the various traits, such as `date` and `meal`, are not set at all; Pantry will set such traits to the empty string.

Example 7.1. Creating the `recipe` element

    <pantry>
    <recipe name="Omari's Chili"
            qty="1" unit="serving"
    </recipe>
    </pantry>

### 7.2.2. Setting the yield of a recipe

Next you will need to set the yield of your recipe. You do this by setting three additional attributes on the `recipe` element: `yieldGrams`, `yieldDesc`, and `servings`. The `servings` attribute is easiest to understand, so we will discuss it first.

#### 7.2.2.1. The `servings` attribute

Often when you make a recipe, you split it into an even number of servings. If that is the case for your recipe, you may enter an appropriate value for the `servings` attribute. Pantry will automatically create a `serving` available unit for the food in this case. If you do not wish to specify a number of servings, you can simply not use the `servings` attribute at all.

For our chili example, we will say that the recipe makes six servings.

#### 7.2.2.2. The `yieldGrams` attribute

In order for Pantry to accurately calculate the nutrient content of a particular amount of food, it needs to know what the total mass of your completed recipe is, after it has been fully prepared (that is, after cooking, baking, mixing, etc., as the case may be.)

Pantry can "guess" what the total mass of your completed recipe is. Pantry guesses by adding up the mass of all the ingredients you entered for the recipe. To have Pantry guess for you, leave the `yieldGrams` attribute out entirely. However, you will often find that the completed recipe weighs significantly less than the mass of all the ingredients. This is because a lot of water often evaporates as you cook or bake foods. Thus, for the most accurate results, you may enter the mass of your completed recipe so that Pantry may take it into account. To do this, enter the appropriate value (in grams) for the `yieldGrams` attribute.

However, if you have entered a `servings` attribute, and you will use only the `serving` available unit when you use the recipe, then entering a `yieldGrams` attribute will do you no good. This is because Pantry will calculate each serving so that it is the appropriate fraction of the total, but the actual total mass will not matter.

I've weighed a completed batch of chili, so I enter an appropriate amount for the `yieldGrams` attribute.

#### 7.2.2.3. The `yieldDesc` attribute

Finally, you may enter any text you wish for the `yieldDesc` attribute. This text can be used to describe the yield of the recipe. I'll enter appropriate text for our chili example.

#### 7.2.2.4. A complete `recipe` element

Here is an example `recipe` element:

Example 7.2. Setting the recipe yield

    <pantry>
    <recipe name="Omari's Chili"
            qty="1" unit="serving" yieldGrams='2181' servings='6'
            yieldDesc='6 quart pot'>
    </recipe>
    </pantry>

### 7.2.3. Setting the ingredients of a recipe

No recipe is complete without ingredients. Each single ingredient is represented by a `ingredient` element. The `ingredient` element has four attributes: `name`, `qty`, `unit`, `comment`, and `file`.

As you will recall, each ingredient in a Pantry recipe is a another Pantry food. These foods come from another Pantry file. For each ingredient, you will specify the source file by specifying the path to the file in the `file` attribute. It is best to use a full, absolute path specification here. If you use a relative path specification, it will be resolved relative to the working directory of the pantry command when it is run, not the directory of the XML file. This is confusing, which is why I recommend using an absolute path specification.

For each ingredient, Pantry will look in the file specified for the food you specify using the `name` attribute. Unlike much of the rest of Pantry, the text of the `name` attribute is not a regular expression. Instead, you must exactly match every space, and you must exactly match the mixture of upper- and lower-case letters, as well.

The `qty` attribute is simply the quantity of the ingredient. As with most other numeric values in Pantry, you may use an integer, a floating-point number, a fraction, or even a mixed number.

The `unit` attribute is an exact match of the available unit you wish to use for this ingredient. As with the `name` attribute, this is case-sensitive.

Finally, the last attribute, `comment`, is optional. This can be whatever helpful text you may wish to enter.

Here is our chili example, complete with all its ingredients.

Example 7.3. A recipe with its `ingredients`

    <pantry>
    <recipe name="Omari's Chili"
            qty="1" unit="serving" yieldGrams='2181' servings='6'
            yieldDesc='6 quart pot'>

            <ingredient name='Poultry food products, ground turkey, raw'
                qty='1/2' unit='lb' file='/home/massysett/pantry-data/master' />
            <ingredient name='Onions, raw' qty='1' unit='medium (2-1/2" dia)'
                comment='chopped' file='/home/massysett/pantry-data/master' />
            <ingredient name='Peppers, sweet, green, raw' qty='1'
                unit='medium (approx 2-3/4" long, 2-1/2" dia)' comment='chopped'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, pinto, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, black turtle soup, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, kidney, all types, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomatoes, red, ripe, canned, packed in tomato juice'
                qty='14.5' unit='oz' comment='Diced; do not drain'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomato products, canned, paste, with salt added'
                qty='1' unit='can (6 oz)'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Water, tap, drinking' qty='2' unit='cup 8 fl oz'
                file='/home/massysett/pantry-data/master' />
    </recipe>
    </pantry>

### 7.2.4. Setting the available units for a recipe

Finally, you may create additional available units for the food. Pantry automatically creates the `g`, `oz`, and `lb` units for you; in addition, if you specified a `servings` attribute to the `yield` element, as we discussed above, then Pantry will also automatically create a `serving` available unit. If you wish to create any additional available units, you will need to know the weight (in grams) of that unit. If for instance you are entering a recipe for cookies and you want to create an avaiable unit for one cookie, you'll need to know the weight in grams of one cookie.

To create available units, create one or more `unit` elements. Each `unit` element will have both `name` and `grams` attributes. Here I have weighed a single cup of chili so I enter an appropriate amount.

Example 7.4. A recipe's units

    <pantry>
    <recipe name="Omari's Chili"
            qty="1" unit="serving" yieldGrams='2181' servings='6'
            yieldDesc='6 quart pot'>

            <ingredient name='Poultry food products, ground turkey, raw'
                qty='1/2' unit='lb' file='/home/massysett/pantry-data/master' />
            <ingredient name='Onions, raw' qty='1' unit='medium (2-1/2" dia)'
                comment='chopped' file='/home/massysett/pantry-data/master' />
            <ingredient name='Peppers, sweet, green, raw' qty='1'
                unit='medium (approx 2-3/4" long, 2-1/2" dia)' comment='chopped'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, pinto, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, black turtle soup, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, kidney, all types, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomatoes, red, ripe, canned, packed in tomato juice'
                qty='14.5' unit='oz' comment='Diced; do not drain'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomato products, canned, paste, with salt added'
                qty='1' unit='can (6 oz)'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Water, tap, drinking' qty='2' unit='cup 8 fl oz'
                file='/home/massysett/pantry-data/master' />

            <unit name='cup' grams='285' />
    </recipe>
    </pantry>

### 7.2.5. Directions for a recipe

Finally, you need something to tell you how to put together all those ingredients. You can do this by including an optional `directions` element. Enclose each paragraph of your directions inside a `p` element. Eventually I will probably add additional formatting tags, such as `b` and `i`, but for now you're stuck with just `p`.

Example 7.5. Recipe directions

    <pantry>
    <recipe name="Omari's Chili"
            qty="1" unit="serving" yieldGrams='2181' servings='6'
            yieldDesc='6 quart pot'>

            <ingredient name='Poultry food products, ground turkey, raw'
                qty='1/2' unit='lb' file='/home/massysett/pantry-data/master' />
            <ingredient name='Onions, raw' qty='1' unit='medium (2-1/2" dia)'
                comment='chopped' file='/home/massysett/pantry-data/master' />
            <ingredient name='Peppers, sweet, green, raw' qty='1'
                unit='medium (approx 2-3/4" long, 2-1/2" dia)' comment='chopped'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, pinto, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, black turtle soup, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Beans, kidney, all types, mature seeds, canned'
                qty='15' unit='oz' file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomatoes, red, ripe, canned, packed in tomato juice'
                qty='14.5' unit='oz' comment='Diced; do not drain'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Tomato products, canned, paste, with salt added'
                qty='1' unit='can (6 oz)'
                file='/home/massysett/pantry-data/master' />
            <ingredient name='Water, tap, drinking' qty='2' unit='cup 8 fl oz'
                file='/home/massysett/pantry-data/master' />

            <unit name='cup' grams='285' />
            <directions>

                <p>Cook turkey, onions, and bell peppers together in
                    6-quart stockpot until turkey is crumbly and onions
                    are soft. Rinse beans, and toss into pot with
                    remaining ingredients. Cook until thickened. </p>

                <p>Add spices, such as chili powder, red pepper, salt,
                    oregano, garlic powder, and cumin, to taste.</p>

            </directions>
    </recipe>
    </pantry>

Prev | Up | Next
Chapter 7. Adding recipes | Home | 7.3. Using recipes