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, raw
Group: Fruits and Fruit Juices
Refuse: 36 percent Skin
100 g (100g)
Bananas, dehydrated, or banana powder
Group: Fruits and Fruit Juices
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.[5] 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, chocolate, fluid, commercial, reduced fat, with added calcium
Milk, reduced fat, fluid, 2% milkfat, with added nonfat milk solids and vitamin A
Milk, chocolate, fluid, commercial, reduced fat
Milk, reduced fat, fluid, 2% milkfat, with added vitamin A
Milk, reduced fat, fluid, 2% milkfat, protein fortified, with added vitamin A
Milk, buttermilk, fluid, cultured, reduced fat
Milk, reduced fat, fluid, 2% milkfat, with added nonfat milk solids, without added vitamin A
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, cooked, microwave
Apples, raw, without skin, cooked, boiled
Apples, raw, without skin

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.[6]

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. In addition, searches using the --exact-match option are also case sensitive. To make all these searches case insensitive, use the --ignore-case or -i option.



[5] 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.

[6] 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.