2.4. Details on searching
Prev | Chapter 2. Basic Pantry commands | Next

## 2.4. Details on searching

Here are some important details about searching.

### 2.4.1. More traits you may use to search

As you've seen, `name` is one trait you can search by. When searching, you may limit your buffer by any traits you wish. Here are the options you use in order to limit your search by particular traits. As with many Unix commands, you can use either a long option (indicated by two dashes) or a short option (with one dash).

- `-n` or `--name`

- `-g` or `--group`

- `-d` or `--date`

- `-m` or `--meal`

- `-u` or `--unit`

- `-q` or `--qty`

- `-c` or `--comment`

- `-o` or `--order`

You may use as many of these options in a single pantry command as you wish. If you use more than one search option, then Pantry will add foods to the buffer only if they match all the traits you specify:

Example 2.9. Using multiple search options

    $ pantry --name Bananas --print traits master
    Bananas, dehydrated, or banana powder
    Group: Fruits and Fruit Juices
    100 g (100g)
    Bananas, raw
    Group: Fruits and Fruit Juices
    Refuse: 36 percent Skin
    100 g (100g)
    Cereals ready-to-eat, KELLOGG'S, CORN FLAKES With Real Bananas
    Group: Breakfast Cereals
    100 g (100g)

    $ pantry --name Bananas --group Breakfast --print traits master
    Cereals ready-to-eat, KELLOGG'S, CORN FLAKES With Real Bananas
    Group: Breakfast Cereals
    100 g (100g)

### 2.4.2. Searches are regular expressions

A very important detail about searches is that all search patterns are regular expressions.[4] This allows you to be very flexible in how you specify your searches. You've already seen one consequence of this: a search pattern only needs to match a portion of a trait in order for that food to be included in the results--that is, `--name Bananas` matches foods that have "Bananas" anywhere in their name.

If you don't want to learn regular expressions, that's okay. Simple searches using just letters and numbers will work just fine. However, you should know that the following characters have special meanings in regular expressions:

    [\^$.|?*+()

If you don't know regular expressions, avoid including any of these characters in your search patterns. Remember to quote your search patterns if they include spaces. For example:`pantry --name 'Bananas, raw' --print traits-units master`.

If you want to learn more about the power of regular expressions, this website is a great place to start. For those already familiar with regular expressions, following is an example of how they can come in handy. This also demonstrates the power of Pantry's command line interface, as it is easy to use Pantry with other Unix programs such as wc, which counts words and lines.

Example 2.10. Using regular expressions

    $ pantry --name Milk --print names master | wc -l
    54

    $ pantry --name "Milk.*reduced" --print names master
    Milk, reduced fat, fluid, 2% milkfat, with added vitamin A
    Milk, buttermilk, fluid, cultured, reduced fat
    Milk, reduced fat, fluid, 2% milkfat, with added nonfat milk solids and vitamin A
    Milk, reduced fat, fluid, 2% milkfat, protein fortified, with added vitamin A
    Milk, chocolate, fluid, commercial, reduced fat
    Milk, reduced fat, fluid, 2% milkfat, with added nonfat milk solids, without added vitamin A
    Milk, chocolate, fluid, commercial, reduced fat, with added calcium
    Milk, dry, nonfat, calcium reduced

As the previous example shows if your search pattern includes characters that are special to your shell, remember to quote it--but you already knew that if you're familiar with regular expressions.

### 2.4.3. My search is returning foods I don't want!

Because search patterns are regular expressions, they will sometimes return more foods than you are interested in. In the next example, I only want to know about `Apples, raw, without skin`. However, the buffer also includes two other foods that contain that same string:

Example 2.11. A search that has more foods than I am interested in

    $ pantry --name "Apples, raw, without skin" --print names \
    > master
    Apples, raw, without skin
    Apples, raw, without skin, cooked, boiled
    Apples, raw, without skin, cooked, microwave

There are two ways to fix this. The first way is to use a feature of regular expressions called anchors. The `$` anchor matches the end of the string. Here, it tells Pantry that there cannot be any characters between `Apples, raw, without skin` and the end of the `name` trait. The anchor is only the dollar sign; the backslash is there in order to keep the shell from giving the dollar sign a special meaning. See this webpage for more information on why you need to quote characters in Unix shells.[5]

Example 2.12. Using anchors

    $ pantry --name "Apples, raw, without skin\$" --print names \
    > master
    Apples, raw, without skin

Another way to fix this problem is to use the `--exact-match` or `-x` option. This option changes all `search options` so that they no longer use regular expressions. Instead, with this option, a food's traits must exactly match the search options in order to be included in the buffer.

Example 2.13. Using the `--exact-match` option

    $ pantry --exact-match --name "Apples, raw, without skin" \
    > --print names master
    Apples, raw, without skin

### 2.4.4. Searches are case sensitive

By default, all searches in Pantry are case sensitive. This is true both for searches by trait as well as when you are using the `--c-unit` option. To make these searches case insensitive, use the `--ignore-case` or `-i` option. In addition, searches using the `--exact-match` option are also case sensitive. The `--ignore-case` option has no effect when using the `--exact-match` option; that is, `--exact-match` searches are always case sensitive.

[4] Regular expression gurus will appreciate knowing that Pantry uses Perl-compatible regular expressions. Links from this page will help give you an idea of what this means. If you are familiar with the Unix command-line utilities grep and egrep, the regular expressions used in Pantry are most similar to those used in egrep. The Python documentation gives the definitive guide to Pantry's regular expression syntax.

[5] An easy solution in this example would have been to use single quotes, but due to idiosyncracies in the scripts that automatically build the examples for the documentation, all the examples in the user guide use double quotes instead.

Prev | Up | Next
2.3. Using the `--print` option | Home | 2.5. Changing food traits