PANTRY(1)

NAME
pantry - nutrient analyzer

SYNOPSIS

pantry [options...] [file...]

pantry [--dump dumpable]

DESCRIPTION

pantry copies foods from FILEs into a buffer. All foods are copied, unless SEARCH OPTIONS are specified, in which case only matching foods are copied. SEARCH OPTIONS are cumulative. pantry then changes every food in the buffer using any CHANGE OPTIONS specified.

If --edit or --delete is specified, pantry deletes the unchanged foods from the corresponding original FILEs. If --edit is specified, pantry adds changed foods to corresponding original FILEs.

If --print REPORT is specified, buffer is printed using REPORT If --nutrient-list NUTRIENT-LIST is specified, buffer is printed using NUTRIENT-LIST; otherwise, the default nutrient list is used. Buffer is unsorted unless --sort TRAITS is specified.

If --add is specified, each food in the buffer is added to FILE.

OPTIONS

Pantry uses Perl compatible regular expressions.

Search options

-n regexp, --name regexp
    Include foods whose name trait matches regexp.

-g regexp, --group regexp
    Include foods whose group trait matches regexp.

-d regexp, --date regexp
    Include foods whose date trait matches regexp.

-m regexp, --meal regexp
    Include foods whose meal trait matches regexp.

-u regexp, --unit regexp
    Include foods whose unit trait matches regexp.

-c regexp, --comment regexp
    Include foods whose comment trait matches regexp.

-q number, --qty number
    Include foods whose qty trait matches number.

-o regexp, --order regexp
    Include foods whose order trait matches regexp.

Change options

-N string, --c-name string
    Change name trait to string.

-G string, --c-group string
    Change group trait to string.

-D string, --c-date string
    Change date trait to string.

-M string, --c-meal string
    Change meal trait to string.

-U regexp, --c-unit regexp
    Search each food's available units using regexp. If there is exactly one match, set unit trait to that match; otherwise, print warning, remove food from buffer, and do not process the --delete or --edit options for this food.

-C string, --c-comment string
    Change comment trait to string.

-Q number, --c-qty number
    Change qty trait to number.

-O string, --c-order string
    Change order trait to string.

--by-nut regexp amount
    Change quantity of food so that amount of nutrient matched by regexp equals amount

--by-cal -K amount
    Same as --by-nut Calories amount

--refuse -R
    Reduce qty of every food in buffer by its corresponding refuse trait

--auto-order, -A
    When adding each food to files specified with --add, pantry will search the file for other foods with identical date and meal traits. The result will be sorted in ascending order by the order trait. If the highest food's order trait matches the regular expression ^[0-9]{4}$, then pantry will take the highest food's order trait, remove any leading zeroes, removes the last digit, and increment the result by one. The result is multiplied by ten, and then is left-padded with zeroes so that it is four characters long. pantry will then change the order trait of the food to the result before adding it to the file.

    If there are no foods with identical date and meal traits, then pantry will set the food's order trait to 0010.

    --auto-order has no effect when adding foods to Foods Text files.

Print options

-p report, --print report
    Print buffer using report.

-l nutrient-list, --nutrient-list nutrient-list
    use nutrient-list when printing report

-s traits, --sort traits
    Sorts foods by trait when printing a report. Specify traits by their first letter; for example, to sort by name, date, and meal, specify --sort ndm. Use lower-case letters to sort in ascending order; use upper-case letters to sort in descending order.

Other general options

-i, --ignore-case
    Make all Search options, and the --c-unit option, case insensitive

-x, --exact-match
    Arguments to Search options, to --c-unit option, and to --by-nut option must exactly match food traits or nutrient names, rather than using regular expressions

-a file, --add file,
    Add buffer to file. To specify multiple files, use multiple --add options, e.g. --add file1 --add file2.

--edit
    Delete original foods from corresponding source files, and add changed foods to corresponding source files

--delete
    Delete original foods from corresponding source files

Other options

--force-valid
    Ordinarily pantry automatically validates all XML files unless they are over 300 kilobytes in size; use this option to validate all XML files regardless of their size.

--skip-valid
    Do not validate any XML files

-h, --help
    Show brief help message and exit

--version
    Print version information and exit

--dump
    Display an internal Pantry variable and exit (see DUMP OPTIONS below)

REPORTS

Two types of reports are available. Food reports are printed once per food in the buffer. Summary reports are printed once for the entire buffer. To print more than one report, specify each report name, separated by dashes; for example, --print names-nuts. Reports may also be specified with an unambiguous specification of the first letters of the report, such as --print na-nu.

The following reports are available:

Food reports

names
    Food names

traits
    Food traits

units
    Available units. g, oz, and lb are not printed as these are available for every food.

measures
    Like units, but also shows the gram weight of every unit. Shows all available units, including g, oz, and lb.

nuts
    Nutrients. For details of how pantry decides which nutrients to print, and what all the columns in this report mean, see the section called “NUTRIENT LISTS”.

blank
    A blank line

paste
    Each food name, printed with one available unit per line; quoted so that output may be easily pasted into subsequent pantry commands.

yield
    The yield of a recipe: its total gram weight, description of yield, and number of servings. Prints warning for foods that are not recipes.

ingredients
    Each ingredient of a recipe; prints warning for foods that are not recipes.

directions
    A recipe's directions; prints warning for foods that are not recipes.

recipe
    Same as names-makes-blank-ingredients-blank-directions.

Summary reports

sum
    Nutrient total of all nutrients in the buffer

groups
    Group names, the number of foods in each group, and the total number of foods in the buffer

list
    The nutrient list, along with its goals

NUTRIENT LISTS

A nutrient report has four columns. The first shows the name of the nutrient. The second column shows the amount (both the numeric amount and the units.) The third column shows this nutrient's percent of a nutrient goal, or blank if that nutrient has no goal. The fourth column shows this nutrient's percentage of the total nutrients in this buffer. The fourth column is not present in sum reports.

The nutrient-list parameter determines which nutrients are shown and in what order, as well as determining what goals are used to calculate the third column. The user may configure her own nutrient-lists in pantryrc.xml(5). The following default nutrient lists are available:

facts
    Mimics the USA "Nutrition Facts" panel.

dv
    Nutrients for which there is a USA FDA Daily Value.

all
    All nutrients.

short
    Only Calories, Total Fat, Total Carbohydrate, and Protein.

DUMP OPTIONS

--dump takes a single argument, which will print one of the following pantry internal variables. After printing the variable, pantry will exit.

version
    Version and copyright information; same as --version.

pantryDTD
    DTD used to validate Pantry XML files

rcDTD
    DTD used to validate pantryrc files

config
    All configuration variables after the pantryrc is processed

BUGS

Under certain circumstances, consumes about 100MB of RAM, though briefly, when buffer totals about 7,000 foods (the number in the USDA database.)

Pantry is not a perfect UNIX citizen because it will not read its data from standard input; thus, Pantry cannot be used as a filter.

Pantry's core file format is a dbm database, not a text file; this is a primary reason the above bug will likely never be fixed.

Report additional bugs to <pantry-users@lists.sourceforge.net>.

VERSION

This manual page written for Pantry version 23.

AUTHOR

Omari Norman

    Author.

COPYRIGHT

Pantry, command-line nutrient analysis.

Version 23, released Friday, November 09, 2007.

Copyright 2007 Omari Norman.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Pantry's "built-in" XML validator is a modified version of xmlproc. xmlproc is Copyright 1998-2000 by Lars Marius Garshol, Oslo, Norway.

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that modified copies are clearly marked as such.

LARS MARIUS GARSHOL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL LARS MARIUS GARSHOL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.