.\"     Title: pantry
.\"    Author: Omari Norman
.\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
.\"      Date: 11/09/2007
.\"    Manual: Reference pages
.\"    Source: Version 23 released Friday, November 09, 2007
.\"
.TH "PANTRY" "1" "11/09/2007" "Version 23 released Friday, No" "Reference pages"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
pantry \- nutrient analyzer
.SH "SYNOPSIS"
.HP 7
\fBpantry\fR [options...] [\fIfile\fR...]
.HP 7
\fBpantry\fR [\-\-dump\ \fIdumpable\fR]
.SH "DESCRIPTION"
.PP

\fBpantry\fR
copies foods from
\fIFILE\fRs into a buffer. All foods are copied, unless
\fBSEARCH OPTIONS\fR
are specified, in which case only matching foods are copied.
\fBSEARCH OPTIONS\fR
are cumulative.
\fBpantry\fR
then changes every food in the buffer using any
\fBCHANGE OPTIONS\fR
specified.
.PP
If
\fB\-\-edit\fR
or
\fB\-\-delete\fR
is specified,
\fBpantry\fR
deletes the unchanged foods from the corresponding original
\fIFILE\fRs. If
\fB\-\-edit\fR
is specified,
\fBpantry\fR
adds changed foods to corresponding original
\fIFILE\fRs.
.PP
If
\fB\-\-print \fR\fB\fIREPORT\fR\fR
is specified, buffer is printed using
\fIREPORT\fR
If
\fB\-\-nutrient\-list \fR\fB\fINUTRIENT\-LIST\fR\fR
is specified, buffer is printed using
\fINUTRIENT\-LIST\fR; otherwise, the default nutrient list is used. Buffer is unsorted unless
\fB\-\-sort TRAITS\fR
is specified.
.PP
If
\fB\-\-add\fR
is specified, each food in the buffer is added to
\fIFILE\fR.
.SH "OPTIONS"
.PP
Pantry uses Perl compatible regular expressions.
.PP
\fBSearch options\fR
.PP
\fB\-n\fR \fIregexp\fR, \fB\-\-name\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIname\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-g\fR \fIregexp\fR, \fB\-\-group\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIgroup\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-d\fR \fIregexp\fR, \fB\-\-date\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIdate\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-m\fR \fIregexp\fR, \fB\-\-meal\fR \fIregexp\fR
.RS 3n
Include foods whose
\fImeal\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-u\fR \fIregexp\fR, \fB\-\-unit\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIunit\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-c\fR \fIregexp\fR, \fB\-\-comment\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIcomment\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fB\-q\fR \fInumber\fR, \fB\-\-qty\fR \fInumber\fR
.RS 3n
Include foods whose
\fIqty\fR
trait matches
\fInumber\fR.
.RE
.PP
\fB\-o\fR \fIregexp\fR, \fB\-\-order\fR \fIregexp\fR
.RS 3n
Include foods whose
\fIorder\fR
trait matches
\fIregexp\fR.
.RE
.PP
\fBChange options\fR
.PP
\fB\-N\fR \fIstring\fR, \fB\-\-c\-name\fR \fIstring\fR
.RS 3n
Change
\fIname\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-G\fR \fIstring\fR, \fB\-\-c\-group\fR \fIstring\fR
.RS 3n
Change
\fIgroup\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-D\fR \fIstring\fR, \fB\-\-c\-date\fR \fIstring\fR
.RS 3n
Change
\fIdate\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-M\fR \fIstring\fR, \fB\-\-c\-meal\fR \fIstring\fR
.RS 3n
Change
\fImeal\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-U\fR \fIregexp\fR, \fB\-\-c\-unit\fR \fIregexp\fR
.RS 3n
Search each food's available units using
\fIregexp\fR. If there is exactly one match, set
\fIunit\fR
trait to that match; otherwise, print warning, remove food from buffer, and do not process the
\fB\-\-delete\fR
or
\fB\-\-edit\fR
options for this food.
.RE
.PP
\fB\-C\fR \fIstring\fR, \fB\-\-c\-comment\fR \fIstring\fR
.RS 3n
Change
\fIcomment\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-Q\fR \fInumber\fR, \fB\-\-c\-qty\fR \fInumber\fR
.RS 3n
Change
\fIqty\fR
trait to
\fInumber\fR.
.RE
.PP
\fB\-O\fR \fIstring\fR, \fB\-\-c\-order\fR \fIstring\fR
.RS 3n
Change
\fIorder\fR
trait to
\fIstring\fR.
.RE
.PP
\fB\-\-by\-nut\fR \fIregexp\fR \fIamount\fR
.RS 3n
Change quantity of food so that amount of nutrient matched by
\fIregexp\fR
equals
\fIamount\fR
.RE
.PP
\fB\-\-by\-cal\fR \fB\-K\fR \fIamount\fR
.RS 3n
Same as
\fB\-\-by\-nut\fR
\fICalories\fR
\fIamount\fR
.RE
.PP
\fB\-\-refuse\fR \fB\-R\fR
.RS 3n
Reduce qty of every food in buffer by its corresponding refuse trait
.RE
.PP
\fB\-\-auto\-order\fR, \fB\-A\fR
.RS 3n
When adding each food to files specified with
\fB\-\-add\fR,
\fBpantry\fR
will search the file for other foods with identical
\fIdate\fR
and
\fImeal\fR
traits. The result will be sorted in ascending order by the
\fIorder\fR
trait. If the highest food's
\fIorder\fR
trait matches the regular expression
^[0\-9]{4}$, then
\fBpantry\fR
will take the highest food's
\fIorder\fR
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.
\fBpantry\fR
will then change the
\fIorder\fR
trait of the food to the result before adding it to the file.
.sp
If there are no foods with identical
\fIdate\fR
and
\fImeal\fR
traits, then
\fBpantry\fR
will set the food's
\fIorder\fR
trait to
0010.
.sp
\fB\-\-auto\-order\fR
has no effect when adding foods to Foods Text files.
.RE
.PP
\fBPrint options\fR
.PP
\fB\-p\fR \fIreport\fR, \fB\-\-print\fR \fIreport\fR
.RS 3n
Print buffer using
\fIreport\fR.
.RE
.PP
\fB\-l\fR \fInutrient\-list\fR, \fB\-\-nutrient\-list\fR \fInutrient\-list\fR
.RS 3n
use
\fInutrient\-list\fR
when printing report
.RE
.PP
\fB\-s\fR \fItraits\fR, \fB\-\-sort\fR \fItraits\fR
.RS 3n
Sorts foods by trait when printing a report. Specify traits by their first letter; for example, to sort by name, date, and meal, specify
\fB\-\-sort ndm\fR. Use lower\-case letters to sort in ascending order; use upper\-case letters to sort in descending order.
.RE
.PP
\fBOther general options\fR
.PP
\fB\-i\fR, \fB\-\-ignore\-case\fR
.RS 3n
Make all
\fBSearch options\fR, and the
\fB\-\-c\-unit\fR
option, case insensitive
.RE
.PP
\fB\-x\fR, \fB\-\-exact\-match\fR
.RS 3n
Arguments to
\fBSearch options\fR, to
\fB\-\-c\-unit\fR
option, and to
\fB\-\-by\-nut\fR
option must exactly match food traits or nutrient names, rather than using regular expressions
.RE
.PP
\fB\-a\fR \fIfile\fR, \fB\-\-add\fR \fIfile\fR,
.RS 3n
Add buffer to
\fIfile\fR. To specify multiple files, use multiple
\fB\-\-add\fR
options, e.g.
\fB\-\-add file1 \-\-add file2\fR.
.RE
.PP
\fB\-\-edit\fR
.RS 3n
Delete original foods from corresponding source files, and add changed foods to corresponding source files
.RE
.PP
\fB\-\-delete\fR
.RS 3n
Delete original foods from corresponding source files
.RE
.PP
\fBOther options\fR
.PP
\fB\-\-force\-valid\fR
.RS 3n
Ordinarily
\fBpantry\fR
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.
.RE
.PP
\fB\-\-skip\-valid\fR
.RS 3n
Do not validate any XML files
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 3n
Show brief help message and exit
.RE
.PP
\fB\-\-version\fR
.RS 3n
Print version information and exit
.RE
.PP
\fB\-\-dump\fR
.RS 3n
Display an internal Pantry variable and exit (see DUMP OPTIONS below)
.RE
.SH "REPORTS"
.PP
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,
\fB\-\-print names\-nuts\fR. Reports may also be specified with an unambiguous specification of the first letters of the report, such as
\fB\-\-print na\-nu\fR.
.PP
The following reports are available:
.PP
\fBFood reports\fR
.PP
\fInames\fR
.RS 3n
Food names
.RE
.PP
\fItraits\fR
.RS 3n
Food traits
.RE
.PP
\fIunits\fR
.RS 3n
Available units.
\fIg\fR,
\fIoz\fR, and
\fIlb\fR
are not printed as these are available for every food.
.RE
.PP
\fImeasures\fR
.RS 3n
Like
\fIunits\fR, but also shows the gram weight of every unit. Shows all available units, including
\fIg\fR,
\fIoz\fR, and
\fIlb\fR.
.RE
.PP
\fInuts\fR
.RS 3n
Nutrients. For details of how
\fBpantry\fR
decides which nutrients to print, and what all the columns in this report mean, see
the section called \(lqNUTRIENT LISTS\(rq.
.RE
.PP
\fIblank\fR
.RS 3n
A blank line
.RE
.PP
\fIpaste\fR
.RS 3n
Each food name, printed with one available unit per line; quoted so that output may be easily pasted into subsequent
\fBpantry\fR
commands.
.RE
.PP
\fIyield\fR
.RS 3n
The yield of a recipe: its total gram weight, description of yield, and number of servings. Prints warning for foods that are not recipes.
.RE
.PP
\fIingredients\fR
.RS 3n
Each ingredient of a recipe; prints warning for foods that are not recipes.
.RE
.PP
\fIdirections\fR
.RS 3n
A recipe's directions; prints warning for foods that are not recipes.
.RE
.PP
\fIrecipe\fR
.RS 3n
Same as
\fBnames\-makes\-blank\-ingredients\-blank\-directions\fR.
.RE
.PP
\fBSummary reports\fR
.PP
\fIsum\fR
.RS 3n
Nutrient total of all nutrients in the buffer
.RE
.PP
\fIgroups\fR
.RS 3n
Group names, the number of foods in each group, and the total number of foods in the buffer
.RE
.PP
\fIlist\fR
.RS 3n
The nutrient list, along with its goals
.RE
.SH "NUTRIENT LISTS"
.PP
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
\fIsum\fR
reports.
.PP
The
\fInutrient\-list\fR
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
\fInutrient\-list\fRs in
\fBpantryrc.xml\fR(5). The following default
\fInutrient lists\fR
are available:
.PP
\fIfacts\fR
.RS 3n
Mimics the USA "Nutrition Facts" panel.
.RE
.PP
\fIdv\fR
.RS 3n
Nutrients for which there is a USA FDA Daily Value.
.RE
.PP
\fIall\fR
.RS 3n
All nutrients.
.RE
.PP
\fIshort\fR
.RS 3n
Only
\fICalories\fR,
\fITotal Fat\fR,
\fITotal Carbohydrate\fR, and
\fIProtein\fR.
.RE
.SH "DUMP OPTIONS"
.PP

\fB\-\-dump\fR
takes a single argument, which will print one of the following
\fBpantry\fR
internal variables. After printing the variable,
\fBpantry\fR
will exit.
.PP
\fIversion\fR
.RS 3n
Version and copyright information; same as
\fB\-\-version\fR.
.RE
.PP
\fIpantryDTD\fR
.RS 3n
DTD used to validate Pantry XML files
.RE
.PP
\fIrcDTD\fR
.RS 3n
DTD used to validate
\fIpantryrc\fR
files
.RE
.PP
\fIconfig\fR
.RS 3n
All configuration variables after the
\fIpantryrc\fR
is processed
.RE
.SH "BUGS"
.PP
Under certain circumstances, consumes about 100MB of RAM, though briefly, when buffer totals about 7,000 foods (the number in the USDA database.)
.PP
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.
.PP
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.
.PP
Report additional bugs to
<pantry\-users@lists.sourceforge.net>.
.SH "VERSION"
.PP
This manual page written for Pantry version 23.
.SH "AUTHOR"
.PP
\fBOmari Norman\fR
.sp -1n
.IP "" 3n
Author.
.SH "COPYRIGHT"
.PP
Pantry, command\-line nutrient analysis.
.PP
Version 23, released Friday, November 09, 2007.
.PP
Copyright 2007 Omari Norman.
.PP
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:
.PP
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
.PP
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.
.PP
Pantry's "built\-in" XML validator is a modified version of xmlproc. xmlproc is Copyright 1998\-2000 by Lars Marius Garshol, Oslo, Norway.
.PP
All Rights Reserved
.PP
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.
.PP
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.
.br